salsalabs 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+.yardoc
+Gemfile.lock
+doc

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+salsa_labs

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p545

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3
+env:
+  global:
+    - secure: PEgtKoeN3s+ovOFmPfLrYXgY3N1S1UFYuFvSVwXRsjNJtYv0+gHBLRMGBregMbcx6fyfiuR6nUykJHVzhBXncvRXjJe/ClTuWJCubvEEAiFg1IU1Z/692KS79EPTKhJoWW/Pqp6lmUN9Xpf/LtngciiFAoF3qHyGXgxU/NOKZwI=
+    - secure: m9PNJdttvjaOzgp7LYrLGwhNuO0kDtaV/Md0EFMwsckCqPZq3549hs4JLH2RZV+oKyKO7nuWBCu670txrskFxPWa4grF/H6q1eUoFcuqgk0iR179mfO20cXU3jTfGzmPseFlpMpSM65dNtH4bdx53tsflfSnG0fCKQJ1FpY1ZsU=
+script:
+  - bundle exec rake spec:ci

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,27 @@
+[![Code Climate](https://codeclimate.com/github/marclove/salsa_labs.png)](https://codeclimate.com/github/marclove/salsa_labs)
+[![Build Status](https://travis-ci.org/marclove/salsalabs.svg?branch=master)](https://travis-ci.org/marclove/salsalabs)
+
+# SalsaLabs
+A Ruby Gem for consuming the [Salsa Labs API](http://wfc2.wiredforchange.com/o/8001/p/salsa/website/public2/commons/dev/docs/).
+
+##Usage
+**This gem is still in a very alpha state and should not be used in production environments. The gem has purposely not been built or deployed to RubyGems. It will not be published until it is in a somewhat usable state.**
+
+Configure the gem with your Salsa Labs login credentials:
+
+```ruby
+SalsaLabs.configure do |c|
+  c.email    = 'myemail@example.com'
+  c.password = 'mypassword'
+end
+```
+
+Make your requests:
+
+```ruby
+SalsaLabs::Supporter.get('12345')
+  #=> { "supporter_KEY" => "12345", "First_Name" => "Jane", "Last_Name" => "Doe", ... }
+
+SalsaLabs::Supporter.all
+  #=> [{ "supporter_KEY" => "12345", "First_Name" => "Jane", "Last_Name" => "Doe", ... }, { "supporter_KEY" => "12346", "First_Name" => "John", "Last_Name" => "Doe", ... }]
+```

data/Rakefile

@@ -0,0 +1,49 @@
+require 'bundler'
+Bundler.setup
+
+require 'rake'
+require 'rspec/core/rake_task'
+require 'yard'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'salsa_labs/version'
+
+task :gem => :build
+task :build do
+  system 'gem build salsalabs.gemspec'
+end
+
+task :install => :build do
+  system "gem install salsalabs-#{SalsaLabs::VERSION}.gem"
+end
+
+task :release => :build do
+  system "git tag -a v#{SalsaLabs::VERSION} -m 'Tagging #{SalsaLabs::VERSION}"
+  system "git push --tags"
+  system "gem push salsalabs-#{SalsaLabs::VERSION}.gem"
+end
+
+namespace :spec do
+  RSpec::Core::RakeTask.new(:unit) do |t|
+    t.verbose = false
+    t.pattern = './spec/unit{,/*/**}/*_spec.rb'
+    t.ruby_opts = "-w -I ./spec -rspec_helper"
+  end
+
+  RSpec::Core::RakeTask.new(:integration) do |t|
+    t.verbose = false
+    t.pattern = './spec/integration{,/*/**}/*_spec.rb'
+    t.ruby_opts = "-w -I ./spec -rspec_helper"
+  end
+
+  task :ci => ['spec:unit','spec:integration']
+end
+
+task :spec => ['spec:unit']
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['--embed-mixins', '--protected', '--private', '--readme', 'README.md']
+end
+
+task :default => :spec

data/lib/salsa_labs/api_response.rb

@@ -0,0 +1,55 @@
+module SalsaLabs
+  class ApiResponse
+
+    # @param [Faraday::Response] faraday_response
+    def initialize(faraday_response)
+      @response = faraday_response
+    end
+
+    # @return [Boolean] true if response was properly formed and
+    #   no error message was returned
+    def successful?
+      data && !error_message
+    end
+
+    # @return [Boolean] true if an error message is returned that
+    #   indicates the current session has expired
+    def needs_reauthentication?
+      return false unless error
+      error =~ /Please authenticate in order to continue./
+    end
+
+    # @return [Nokogiri::XML] the full xml returned by the API,
+    #   parsed by +Nokogiri+ (memoized)
+    def body
+      @body ||= Nokogiri::XML(@response.body)
+    end
+
+    # @return [String] the error message returned by the API
+    # @return [nil] if there was no error message returned by the API
+    def error_message
+      if data.nil?
+        'The response was not formatted as expected.'
+      elsif error
+        error
+      else
+        nil
+      end
+    end
+
+    # @return [String] the xml fragment contained in the
+    #   +<data></data>+ element of the API response
+    # @return [nil] if there was no data returned by the API
+    def data
+      data = body.xpath('//data')
+      data.children.length == 0 ? nil : data.children.to_s
+    end
+
+    # @return [String] the error message returned by the API
+    # @return [nil] if there was no error message returned by the API
+    def error
+      err = body.xpath('//data/error').text
+      err == '' ? nil : err
+    end
+  end
+end

data/lib/salsa_labs/authentication_response.rb

@@ -0,0 +1,44 @@
+require 'nokogiri'
+
+module SalsaLabs
+  class AuthenticationResponse
+
+    # @param [Faraday::Response] faraday_response
+    def initialize(faraday_response)
+      @response = faraday_response
+    end
+
+    # @return [String]
+    def session_cookies
+      returned_cookies if successful?
+    end
+
+    # @return [Boolean] true if no error message was returned
+    def successful?
+      !error_message && session_cookie_exists?
+    end
+
+    # @return [Nokogiri::XML] the full xml returned by the API,
+    #   parsed by +Nokogiri+ (memoized)
+    def body
+      @body ||= ::Nokogiri::XML(@response.body)
+    end
+
+    # @return [String] the error message returned by the API
+    # @return [nil] if there was no error message returned by the API
+    def error_message
+      err = body.xpath('//data/error').text
+      err == '' ? nil : err
+    end
+
+    private
+
+    def session_cookie_exists?
+      returned_cookies =~ /JSESSION/
+    end
+
+    def returned_cookies
+      @response.headers['set-cookie']
+    end
+  end
+end

data/lib/salsa_labs/configuration.rb

@@ -0,0 +1,11 @@
+module SalsaLabs
+  class Configuration
+    attr_accessor :email, :password
+
+    # @return [Boolean]
+    #   true if {#email} and {#password} are both not +nil+
+    def valid?
+      !email.nil? && !password.nil?
+    end
+  end
+end

data/lib/salsa_labs/connection.rb

@@ -0,0 +1,91 @@
+require 'net/http'
+require 'cgi'
+require 'faraday'
+require 'salsa_labs/salsa_request_overwrite'
+
+module SalsaLabs
+  class APIResponseError < StandardError; end
+  class AuthenticationError < StandardError; end
+  class AuthenticationLoopError < StandardError; end
+
+  class Connection
+
+    # @param [String] email
+    #   from your Salsa Labs login
+    # @param [String] password
+    #   from your Salsa Labs login
+    def initialize(email, password)
+      @email, @password = email, password
+      @authentication_headers = nil
+    end
+
+    # @param [String] path
+    #   the url fragment that follows "+sandbox.salsalabs.com/+"
+    #   in the endpoint uri you are making a request to
+    # @param [Hash] query
+    #   a hash representing the url query string parameters
+    # @param [Boolean] recursive_call
+    #   whether this method was called by itself
+    # @yield
+    #   the code to execute if the response is successful
+    # @yieldparam [String] response
+    #   the xml fragment contained in the +<data></data>+ element of the API response
+    # @raise [AuthenticationLoopError]
+    #   if the request is caught in an infinite authentication loop
+    # @raise [APIResponseError]
+    #   if the API response returned an error or was malformed
+    def request(path, query={}, recursive_call = false, &block)
+      authenticate unless authenticated?
+
+      execute_request(path, query) do |response|
+        if response.successful?
+          block.call(response.data)
+        elsif response.needs_reauthentication?
+          raise AuthenticationLoopError.new if recursive_call
+          authenticate
+          request(path, query, true, &block)
+        else
+          raise APIResponseError, response.error_message
+        end
+      end
+    end
+
+    private
+
+    # @return [Faraday]
+    def api
+      @api ||= ::Faraday.new url: 'https://sandbox.salsalabs.com/' do |conn|
+        conn.use :salsa
+        conn.adapter :net_http
+      end
+    end
+
+    # @yieldparam [ApiResponse] response
+    def execute_request(path, query={})
+      yield ApiResponse.new(api.get(path, query, @authentication_headers))
+    end
+
+    # Makes an authentication call to the Salsa Labs API using the credentials
+    # set in the {SalsaLabs.configure} method.
+    #
+    # @raise [AuthenticationError] if the response returned an error or is malformed
+    def authenticate
+      email, password = CGI.escape(@email), CGI.escape(@password)
+      auth_path = "api/authenticate.sjs?email=#{email}&password=#{password}"
+      response = AuthenticationResponse.new(api.get(auth_path))
+      if response.successful?
+        @authentication_headers = { 'Cookie' => response.session_cookies }
+      else
+        @authentication_headers = nil
+        raise AuthenticationError, response.error_message
+      end
+    end
+
+    # Returns +true+ if the session cookie has been set.
+    #
+    # @return [Boolean]
+    def authenticated?
+      !!@authentication_headers
+    end
+  end
+end

data/lib/salsa_labs/objects/distributed_event.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class DistributedEvent
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/donation.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class Donation
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/event.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class Event
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/groups.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class Groups
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class Supporter
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_action.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterAction
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_action_comment.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterActionComment
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_action_content.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterActionContent
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_action_target.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterActionTarget
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_event.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterEvent
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/objects/supporter_groups.rb

@@ -0,0 +1,6 @@
+module SalsaLabs
+  class SupporterGroups
+    include SalsaObject
+    # @!parse extend SalsaObject::ClassMethods
+  end
+end

data/lib/salsa_labs/salsa_object.rb

@@ -0,0 +1,74 @@
+require 'active_support/core_ext'
+
+module SalsaLabs
+  module SalsaObject
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # @param [String] key of the object being requested
+      # @return [Hash] a hash representing the requested object
+      def get(key)
+        SalsaLabs.request('api/getObject.sjs', {object: object_name, key: key}) do |response|
+          Hash.from_xml(response).
+               try(:[], object_name).
+               try(:[], 'item')
+        end
+      end
+
+      # @return [Integer] the number of total objects
+      def count
+        SalsaLabs.request('api/getCounts.sjs', {object: object_name}) do |response|
+          Hash.from_xml(response).
+               try(:[], object_name).
+               try(:[], 'count').
+               try(:[], 'count').
+               try(:to_i)
+        end
+      end
+
+      # @return [Array<Hash>] an array of all the objects
+      def all
+        SalsaLabs.request('api/getObjects.sjs', {object: object_name}) do |response|
+          Hash.from_xml(response).
+               try(:[], object_name).
+               try(:[], 'item')
+        end
+      end
+
+      # @return [String] the newly created object's key
+      # @raise [APIResponseError]
+      #   if the request to create the object failed
+      def create(attributes)
+        attributes.merge!({ object: object_name, key: '0' })
+        SalsaLabs.request('save', attributes) do |response|
+          SalsaLabs::SaveResponse.new(response).key
+        end
+      end
+
+      # @return [Boolean] true if request was successful
+      # @raise [APIResponseError]
+      #   if the request to update the object failed
+      def update(key, attributes)
+        attributes.merge!({ object: object_name, key: key.to_s })
+        SalsaLabs.request('save', attributes) do |response|
+          SalsaLabs::SaveResponse.new(response).successful?
+        end
+      end
+
+      private
+
+      # @return [String] the name of this class in lowercase and underscored format
+      # @example
+      #   class MySpecialClass
+      #     include SalsaObject
+      #   end
+      #
+      #   MySpecialClass.object_name #=> 'my_special_class'
+      def object_name
+        self.to_s.split('::').last.gsub(/(?:([A-Za-z])|^)(?=[^a-z])/) { "#{$1}#{$1 && '_'}" }.downcase
+      end
+    end
+  end
+end

data/lib/salsa_labs/salsa_request_overwrite.rb

@@ -0,0 +1,30 @@
+require 'faraday'
+
+module Faraday
+  class SalsaRequestOverwrite < Faraday::Middleware
+    def initialize(app)
+      super(app)
+    end
+
+    def call(env)
+      url = env[:url].to_s
+      rewrite_request(env) if rewrite_request?(url)
+      @app.call(env)
+    end
+
+    def rewrite_request?(url)
+      url =~ /https:\/\/.*\.salsalabs\.com\/save/
+    end
+
+    def rewrite_request(env)
+      url = env[:url].to_s
+      env[:url] = URI(url.sub(/\/save\?/,'/save?xml&'))
+    end
+  end
+end
+
+if Faraday.respond_to?(:register_middleware)
+  Faraday.register_middleware salsa: Faraday::SalsaRequestOverwrite
+elsif Faraday::Middleware.respond_to?(:register_middleware)
+  Faraday::Middleware.register_middleware salsa: Faraday::SalsaRequestOverwrite
+end

data/lib/salsa_labs/save_response.rb

@@ -0,0 +1,29 @@
+module SalsaLabs
+  class SaveResponse
+    # @param [String] an xml string of the response body
+    def initialize(xml)
+      @doc = Nokogiri::XML(xml)
+      raise APIResponseError, 'Save request failed' unless successful?
+    end
+
+    # @return [Boolean] true if request was successful
+    def successful?
+      success_object? && key_returned?
+    end
+
+    # @return [String] the key of the object that was saved
+    def key
+      @doc.xpath('/success').attr('key').to_s
+    end
+
+    private
+
+    def success_object?
+      @doc.xpath('/success').length > 0
+    end
+
+    def key_returned?
+      !key.blank?
+    end
+  end
+end

data/lib/salsa_labs/version.rb

@@ -0,0 +1,3 @@
+module SalsaLabs
+  VERSION = '0.1.0'
+end

data/lib/salsa_labs.rb

@@ -0,0 +1,75 @@
+require 'salsa_labs/configuration'
+require 'salsa_labs/connection'
+require 'salsa_labs/authentication_response'
+require 'salsa_labs/api_response'
+require 'salsa_labs/save_response'
+require 'salsa_labs/salsa_object'
+require 'salsa_labs/objects/distributed_event'
+require 'salsa_labs/objects/donation'
+require 'salsa_labs/objects/event'
+require 'salsa_labs/objects/groups'
+require 'salsa_labs/objects/supporter_action_comment'
+require 'salsa_labs/objects/supporter_action_content'
+require 'salsa_labs/objects/supporter_action_target'
+require 'salsa_labs/objects/supporter_action'
+require 'salsa_labs/objects/supporter_event'
+require 'salsa_labs/objects/supporter_groups'
+require 'salsa_labs/objects/supporter'
+
+module SalsaLabs
+  class ConfigurationError < StandardError
+    # @!attribute [r] message
+    # @return [String]
+    #   the error message
+    def message
+      'You have not properly configured SalsaLabs with your email and password'
+    end
+  end
+
+  # Configures the gem with your Salsa Labs credentials
+  # @note Configuration is required for the gem to function.
+  # @yieldparam [SalsaLabs::Configuration] config
+  #   yields gem's current +Configuration+ object within the block
+  # @example
+  #   SalsaLabs.configure do |c|
+  #     c.email    = 'myemail@example.com'
+  #     c.password = 'mypassword'
+  #   end
+  # @return [SalsaLabs]
+  # @see SalsaLabs::Configuration
+  def self.configure
+    yield configuration
+  end
+
+  # Makes a request to the specified SalsaLabs API endpoint.
+  # @param [String] path
+  #   the url fragment that follows "+sandbox.salsalabs.com/api/+"
+  #   in the endpoint uri you are making a request to
+  # @param [Hash] query
+  #   a hash representing the url query string parameters
+  # @yieldreturn [SalsaLabs::ApiResponse]
+  #   the response object for the executed request
+  # @return [SalsaLabs]
+  def self.request(path, query={}, &block)
+    connection.request(path, query, &block)
+  end
+
+  private
+
+  # @return [SalsaLabs::Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # @return [SalsaLabs::Connection]
+  def self.connection
+    @connection ||= establish_connection
+  end
+
+  # @return [SalsaLabs::Connection]
+  # @raise [ConfigurationError] if the gem has not been configured properly
+  def self.establish_connection
+    raise ConfigurationError.new unless configuration.valid?
+    Connection.new(configuration.email, configuration.password)
+  end
+end

data/salsalabs.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'salsa_labs/version'
+
+Gem::Specification.new do |s|
+  s.name = 'salsalabs'
+  s.version = SalsaLabs::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors = ['Marc Love']
+  s.email = ['marcslove@gmail.com']
+  s.homepage = 'https://github.com/marcslove/salsa_labs'
+  s.summary = 'Salsa Labs API client library'
+  s.licenses = ['MIT']
+  s.required_rubygems_version = '>= 1.3.6'
+  s.add_dependency 'activesupport', '4.0.4'
+  s.add_dependency 'nokogiri'
+  s.add_dependency 'faraday', '>= 0.9.0.rc'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'bundler', '>= 1.0'
+  s.add_development_dependency 'rspec', '>= 2.11'
+  s.add_development_dependency 'webmock', '>= 1.13.0'
+  s.add_development_dependency 'pry-debugger'
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- spec/*`.split("\n")
+end

data/spec/fixtures/auth_error.txt

@@ -0,0 +1,14 @@
+HTTP/1.1 200 OK
+Server: nginx/1.0.0
+Date: Tue, 30 Jul 2013 08:32:07 GMT
+Content-Type: text/xml;charset=UTF-8
+Connection: close
+RequestURI: /api/authenticate.sjs?email=marcslove@gmail.com&password=marclove
+Set-Cookie: JSESSIONID=863F72A0F2BBAA941D2D214DEC9DBE4F-n4; Path=/; Secure; HttpOnly, hqtab_2=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT, READONLY_Short_Name=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT, SRV=sandbox; path=/
+Cache-Control: private
+Transfer-Encoding: Identity
+
+<?xml version="1.0"?>
+<data>
+  <error>Invalid login, please try again.</error>
+</data>