restforce 0.0.1

data/lib/restforce/collection.rb

@@ -0,0 +1,23 @@
+module Restforce
+  class Collection < Array
+    attr_reader :total_size, :next_page_url
+
+    def initialize(hash, client)
+      @client        = client
+      @total_size    = hash['totalSize']
+      @next_page_url = hash['nextRecordsUrl']
+      super(self.build(hash['records']))
+    end
+
+    # Converts an array of Hash's into an array of Restforce::SObject.
+    def build(array)
+      array.map { |record| Restforce::SObject.new(record, @client) }
+    end
+
+    def next_page
+      response = @client.get next_page_url
+      response.body
+    end
+
+  end
+end

data/lib/restforce/config.rb

@@ -0,0 +1,68 @@
+require 'logger'
+
+module Restforce
+  class << self
+    attr_writer :log
+
+    # Returns the current Configuration
+    #
+    # Example
+    #
+    #    Restforce.configuration.username = "username"
+    #    Restforce.configuration.password = "password"
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the Configuration
+    #
+    # Example
+    #
+    #    Restforce.configure do |config|
+    #      config.username = "username"
+    #      config.password = "password"
+    #    end
+    def configure
+      yield configuration
+    end
+
+    def log?
+      @log ||= false
+    end
+
+    def log(message)
+      return unless Restforce.log?
+      Restforce.configuration.logger.send :debug, message
+    end
+  end
+
+  class Configuration
+    attr_accessor :api_version
+    # The username to use during login.
+    attr_accessor :username
+    # The password to use during login.
+    attr_accessor :password
+    # The security token to use during login.
+    attr_accessor :security_token
+    # The OAuth client id
+    attr_accessor :client_id
+    # The OAuth client secret
+    attr_accessor :client_secret
+    # Set this to true if you're authenticating with a Sandbox instance.
+    # Defaults to false.
+    attr_accessor :host
+
+    attr_accessor :oauth_token
+    attr_accessor :refresh_token
+    attr_accessor :instance_url
+
+    def initialize
+      @api_version ||= '24.0'
+      @host        ||= 'login.salesforce.com'
+    end
+
+    def logger
+      @logger ||= ::Logger.new STDOUT
+    end
+  end
+end

data/lib/restforce/mash.rb

@@ -0,0 +1,61 @@
+require 'hashie/mash'
+
+module Restforce
+  class Mash < Hashie::Mash
+
+    class << self
+
+      # Pass in an Array or Hash and it will be recursively converted into the
+      # appropriate Restforce::Collection, Restforce::SObject and
+      # Restforce::Mash objects.
+      def build(val, client)
+        if val.is_a?(Array)
+          val.collect { |e| self.klass(e).new(e, client) }
+        elsif val.is_a?(Hash)
+          self.klass(val).new(val, client)
+        else
+          val
+        end
+      end
+
+      # When passed a hash, it will determine what class is appropriate to
+      # represent the data.
+      def klass(val)
+        if val.has_key? 'records'
+          # When the hash has a records key, it should be considered a collection
+          # of sobject records.
+          Restforce::Collection
+        elsif val.has_key? 'attributes'
+          # When the hash contains an attributes key, it should be considered an
+          # sobject record
+          Restforce::SObject
+        else
+          # Fallback to a standard Restforce::Mash for everything else
+          Restforce::Mash
+        end
+      end
+
+    end
+
+    def initialize(source_hash = nil, client = nil, default = nil, &blk)
+      @client = client
+      deep_update(source_hash) if source_hash
+      default ? super(default) : super(&blk)
+    end
+  
+    def convert_value(val, duping=false)
+      case val
+      when self.class
+        val.dup
+      when ::Hash
+        val = val.dup if duping
+        self.class.klass(val).new(val, @client)
+      when Array
+        val.collect{ |e| convert_value(e) }
+      else
+        val
+      end
+    end
+
+  end
+end

data/lib/restforce/middleware.rb

@@ -0,0 +1,30 @@
+module Restforce
+
+  # Base class that all middleware can extend. Provides some convenient helper
+  # functions.
+  class Middleware < Faraday::Middleware
+
+    def initialize(app, client, options)
+      @app     = app
+      @client  = client
+      @options = options
+    end
+
+    def client
+      @client
+    end
+
+    def connection
+      client.send(:connection)
+    end
+
+  end
+end
+
+require 'restforce/middleware/raise_error'
+require 'restforce/middleware/authentication'
+require 'restforce/middleware/authentication/password'
+require 'restforce/middleware/authentication/oauth'
+require 'restforce/middleware/authorization'
+require 'restforce/middleware/instance_url'
+require 'restforce/middleware/mashify'

data/lib/restforce/middleware/authentication.rb

@@ -0,0 +1,32 @@
+module Restforce
+
+  # Faraday middleware that allows for on the fly authentication of requests.
+  # When a request fails (ie. A status of 401 is returned). The middleware
+  # will attempt to either reauthenticate (username and password) or refresh
+  # the oauth access token (if a refresh token is present).
+  class Middleware::Authentication < Restforce::Middleware
+
+    def call(env)
+      begin
+        @app.call(env)
+      rescue Restforce::UnauthorizedError
+        authenticate!
+        @app.call(env)
+      end
+    end
+
+    def authenticate!
+      raise 'must subclass'
+    end
+
+    def connection
+      @connection ||= Faraday.new(:url => "https://#{@options[:host]}") do |builder|
+        builder.response :json
+        builder.response :logger, Restforce.configuration.logger if Restforce.log?
+        builder.adapter Faraday.default_adapter
+      end
+    end
+  
+  end
+
+end

data/lib/restforce/middleware/authentication/oauth.rb

@@ -0,0 +1,22 @@
+module Restforce
+
+  # Authentication middleware used if oauth_token and refresh_token are set
+  class Middleware::Authentication::OAuth < Restforce::Middleware::Authentication
+
+    def authenticate!
+      response = connection.post '/services/oauth2/token' do |req|
+        req.body = URI.encode_www_form(
+          :grant_type    => 'refresh_token',
+          :refresh_token => @options[:refresh_token],
+          :client_id     => @options[:client_id],
+          :client_secret => @options[:client_secret]
+        )
+      end
+      raise Restforce::AuthenticationError if response.status != 200
+      @options[:instance_url] = response.body['instance_url']
+      @options[:oauth_token]  = response.body['access_token']
+    end
+  
+  end
+
+end

data/lib/restforce/middleware/authentication/password.rb

@@ -0,0 +1,27 @@
+module Restforce
+
+  # Authentication middleware used if username and password flow is used
+  class Middleware::Authentication::Password < Restforce::Middleware::Authentication
+
+    def authenticate!
+      response = connection.post '/services/oauth2/token' do |req|
+        req.body = URI.encode_www_form(
+          :grant_type    => 'password',
+          :client_id     => @options[:client_id],
+          :client_secret => @options[:client_secret],
+          :username      => @options[:username],
+          :password      => password
+        )
+      end
+      raise Restforce::AuthenticationError if response.status != 200
+      @options[:instance_url] = response.body['instance_url']
+      @options[:oauth_token]  = response.body['access_token']
+    end
+
+    def password
+      "#{@options[:password]}#{@options[:security_token]}"
+    end
+  
+  end
+
+end

data/lib/restforce/middleware/authorization.rb

@@ -0,0 +1,19 @@
+module Restforce
+
+  # Piece of middleware that simply injects the OAuth token into the request
+  # headers.
+  class Middleware::Authorization < Restforce::Middleware
+    AUTH_HEADER = 'Authorization'.freeze
+
+    def call(env)
+      env[:request_headers][AUTH_HEADER] = %(OAuth #{token})
+      @app.call(env)
+    end
+
+    def token
+      @options[:oauth_token]
+    end
+  
+  end
+
+end

data/lib/restforce/middleware/instance_url.rb

@@ -0,0 +1,27 @@
+module Restforce
+
+  # Middleware which asserts that the instance_url is always set
+  class Middleware::InstanceURL < Restforce::Middleware
+
+    def call(env)
+      # If the instance url isn't set in options, raise a
+      # Restforce::UnauthorizedError to trigger reauthentication.
+      raise Restforce::UnauthorizedError, 'instance url not set' unless @options[:instance_url]
+
+      # If the url_prefix for the connection doesn't match the instance_url
+      # set in the options, we raise an error which gets caught outside of
+      # middleware, where the url_prefix is then set before retrying the
+      # request. It would be ideal if this could all be handled in
+      # middleware...
+      raise Restforce::InstanceURLError unless connection.url_prefix == instance_url
+
+      @app.call(env)
+    end
+
+    def instance_url
+      URI.parse(@options[:instance_url])
+    end
+  
+  end
+
+end

data/lib/restforce/middleware/mashify.rb

@@ -0,0 +1,18 @@
+module Restforce
+  # Middleware the converts sobject records from JSON into Restforce::SObject objects
+  # and collections of records into Restforce::Collection objects.
+  class Middleware::Mashify < Restforce::Middleware
+
+    def call(env)
+      @env = env
+      response = @app.call(env)
+      env[:body] = Restforce::Mash.build(body, client)
+      response
+    end
+
+    def body
+      @env[:body]
+    end
+  
+  end
+end

data/lib/restforce/middleware/raise_error.rb

@@ -0,0 +1,18 @@
+module Restforce
+  class Middleware::RaiseError < Faraday::Response::Middleware
+    def on_complete(env)
+      case env[:status]
+      when 404
+        raise Faraday::Error::ResourceNotFound, message(env)
+      when 401
+        raise Restforce::UnauthorizedError, message(env)
+      when 400...600
+        raise Faraday::Error::ClientError, message(env)
+      end
+    end
+
+    def message(env)
+      "#{env[:body].first['errorCode']}: #{env[:body].first['message']}"
+    end
+  end
+end

data/lib/restforce/sobject.rb

@@ -0,0 +1,41 @@
+module Restforce
+  class SObject < Restforce::Mash
+
+    def sobject_type
+      self.attributes.type
+    end
+
+    # Public: Persist the attributes to Salesforce.
+    #
+    # Examples
+    #
+    #   account = client.query('select Id, Name from Account').first
+    #   account.Name = 'Foobar'
+    #   account.save
+    def save
+      # Remove 'attributes' and parent/child relationships. We only want to
+      # persist the attributes on the sobject.
+      ensure_id
+      attrs = self.to_hash.reject { |key, _| key =~ /.*__r/ || key =~ /^attributes$/ }
+      @client.update(sobject_type, attrs)
+    end
+
+    # Public: Destroy this record.
+    #
+    # Examples
+    #
+    #   account = client.query('select Id, Name from Account').first
+    #   account.destroy
+    def destroy
+      ensure_id
+      @client.destroy(sobject_type, self.Id)
+    end
+
+  private
+
+    def ensure_id
+      raise 'You need to query the Id for the record first.' unless self.Id?
+    end
+
+  end
+end

data/lib/restforce/version.rb

@@ -0,0 +1,3 @@
+module Restforce
+  VERSION = "0.0.1"
+end

data/restforce.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/restforce/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Eric J. Holmes"]
+  gem.email         = ["eric@ejholmes.net"]
+  gem.description   = %q{A lightweight ruby client for the Salesforce REST api.}
+  gem.summary       = %q{A lightweight ruby client for the Salesforce REST api.}
+  gem.homepage      = "https://github.com/ejholmes/restforce"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "restforce"
+  gem.require_paths = ["lib"]
+  gem.version       = Restforce::VERSION
+
+  gem.add_dependency 'rake'
+  gem.add_dependency 'faraday', '~> 0.8.4'
+  gem.add_dependency 'faraday_middleware', '~> 0.8.8'
+  gem.add_dependency 'json', '~> 1.7.5'
+  gem.add_dependency 'hashie', '~> 1.2.0'
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'webmock'
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'simplecov'
+end

data/spec/fixtures/auth_error_response.json

@@ -0,0 +1 @@
+{"error":"invalid_grant","error_description":"authentication failure - Invalid Password"}