force 0.0.1

data/lib/force/concerns/authentication.rb

@@ -0,0 +1,39 @@
+module Force
+  module Concerns
+    module Authentication
+
+      # Public: Force an authentication
+      def authenticate!
+        raise AuthenticationError, 'No authentication middleware present' unless authentication_middleware
+        middleware = authentication_middleware.new nil, self, options
+        middleware.authenticate!
+      end
+
+      # Internal: Determines what middleware will be used based on the options provided
+      def authentication_middleware
+        if username_password?
+          Force::Middleware::Authentication::Password
+        elsif oauth_refresh?
+          Force::Middleware::Authentication::Token
+        end
+      end
+
+      # Internal: Returns true if username/password (autonomous) flow should be used for
+      # authentication.
+      def username_password?
+        options[:username] &&
+          options[:password] &&
+          options[:client_id] &&
+          options[:client_secret]
+      end
+
+      # Internal: Returns true if oauth token refresh flow should be used for
+      # authentication.
+      def oauth_refresh?
+        options[:refresh_token] &&
+          options[:client_id] &&
+          options[:client_secret]
+      end
+    end
+  end
+end

data/lib/force/concerns/base.rb

@@ -0,0 +1,59 @@
+module Force
+  module Concerns
+    module Base
+      attr_reader :options
+
+      # Public: Creates a new client instance
+      #
+      # options - A hash of options to be passed in (default: {}).
+      #        :username               - The String username to use (required for password authentication).
+      #        :password               - The String password to use (required for password authentication).
+      #        :security_token         - The String security token to use (required for password authentication).
+      #
+      #        :oauth_token            - The String oauth access token to authenticate api
+      #                                  calls (required unless password
+      #                                  authentication is used).
+      #        :refresh_token          - The String refresh token to obtain fresh
+      #                                  oauth access tokens (required if oauth
+      #                                  authentication is used).
+      #        :instance_url           - The String base url for all api requests
+      #                                  (required if oauth authentication is used).
+      #
+      #        :client_id              - The oauth client id to use. Needed for both
+      #                                  password and oauth authentication
+      #        :client_secret          - The oauth client secret to use.
+      #
+      #        :host                   - The String hostname to use during
+      #                                  authentication requests (default: 'login.salesforce.com').
+      #
+      #        :api_version            - The String REST api version to use (default: '24.0')
+      #
+      #        :authentication_retries - The number of times that client
+      #                                  should attempt to reauthenticate
+      #                                  before raising an exception (default: 3).
+      #
+      #        :compress               - Set to true to have Salesforce compress the response (default: false).
+      #        :timeout                - Faraday connection request read/open timeout. (default: nil).
+      #
+      #        :proxy_uri              - Proxy URI: 'http://proxy.example.com:port' or 'http://user@pass:proxy.example.com:port'
+      #
+      #        :authentication_callback
+      #                                - A Proc that is called with the response body after a successful authentication.
+      def initialize(options = {})        
+        @options = Hash[Force.configuration.options.map { |option| [option, Force.configuration.send(option)] }]
+        @options.merge!(options)
+
+        yield builder if block_given?
+      end
+
+      def instance_url
+        authenticate! unless options[:instance_url]
+        options[:instance_url]
+      end
+
+      def inspect
+        "#<#{self.class} @options=#{@options.inspect}>"
+      end
+    end
+  end
+end

data/lib/force/concerns/caching.rb

@@ -0,0 +1,24 @@
+module Force
+  module Concerns
+    module Caching
+      # Public: Runs the block with caching disabled.
+      #
+      # block - A query/describe/etc.
+      #
+      # Returns the result of the block
+      def without_caching(&block)
+        options[:use_cache] = false
+        block.call
+      ensure
+        options.delete(:use_cache)
+      end
+
+      private
+
+      # Internal: Cache to use for the caching middleware
+      def cache
+        options[:cache]
+      end
+    end
+  end
+end

data/lib/force/concerns/canvas.rb

@@ -0,0 +1,10 @@
+module Force
+  module Concerns
+    module Canvas
+      def decode_signed_request(signed_request)
+        raise 'client_secret not set.' unless options[:client_secret]
+        SignedRequest.decode(signed_request, options[:client_secret])
+      end
+    end
+  end
+end

data/lib/force/concerns/connection.rb

@@ -0,0 +1,74 @@
+module Force
+  module Concerns
+    module Connection
+      # Public: The Faraday::Builder instance used for the middleware stack. This
+      # can be used to insert an custom middleware.
+      #
+      # Examples
+      #
+      #   # Add the instrumentation middleware for Rails.
+      #   client.middleware.use FaradayMiddleware::Instrumentation
+      #
+      # Returns the Faraday::Builder for the Faraday connection.
+      def middleware
+        connection.builder
+      end
+
+      alias_method :builder, :middleware
+
+      private
+
+      # Internal: Internal faraday connection where all requests go through
+      def connection
+        @connection ||= Faraday.new(options[:instance_url], connection_options) do |builder|
+          # Parses JSON into Hashie::Mash structures.
+          builder.use      Force::Middleware::Mashify, self, options
+          # Handles multipart file uploads for blobs.
+          builder.use      Force::Middleware::Multipart
+          # Converts the request into JSON.
+          builder.request  :json
+          # Handles reauthentication for 403 responses.
+          builder.use      authentication_middleware, self, options if authentication_middleware
+          # Sets the oauth token in the headers.
+          builder.use      Force::Middleware::Authorization, self, options
+          # Ensures the instance url is set.
+          builder.use      Force::Middleware::InstanceURL, self, options
+          # Parses returned JSON response into a hash.
+          builder.response :json, :content_type => /\bjson$/
+          # Caches GET requests.
+          builder.use      Force::Middleware::Caching, cache, options if cache
+          # Follows 30x redirects.
+          builder.use      FaradayMiddleware::FollowRedirects
+          # Raises errors for 40x responses.
+          builder.use      Force::Middleware::RaiseError
+          # Log request/responses
+          builder.use      Force::Middleware::Logger, Force.configuration.logger, options if Force.log?
+          # Compress/Decompress the request/response
+          builder.use      Force::Middleware::Gzip, self, options
+
+          builder.adapter  adapter
+        end
+      end
+
+      def adapter
+        options[:adapter]
+      end
+
+      # Internal: Faraday Connection options
+      def connection_options
+        { :request => {
+            :timeout => options[:timeout],
+            :open_timeout => options[:timeout] },
+          :proxy => options[:proxy_uri],
+          :ssl => {:verify => false}
+        }
+      end
+
+      # Internal: Returns true if the middlware stack includes the
+      # Force::Middleware::Mashify middleware.
+      def mashify?
+        middleware.handlers.index(Force::Middleware::Mashify)
+      end
+    end
+  end
+end

data/lib/force/concerns/picklists.rb

@@ -0,0 +1,87 @@
+module Force
+  module Concerns
+    module Picklists
+      # Public: Get the available picklist values for a picklist or multipicklist field.
+      #
+      # sobject - The String name of the sobject.
+      # field   - The String name of the picklist/multipicklist field.
+      # options - A hash of options. (default: {}).
+      #           :valid_for - If specified, will only return picklist values
+      #                        that are valid for the controlling picklist
+      #                        value
+      #
+      # Examples
+      #
+      #   client.picklist_values('Account', 'Type')
+      #   # => [#<Force::Mash label="Prospect" value="Prospect">]
+      #
+      #   # Given a custom object named Automobile__c with picklist fields
+      #   # Model__c and Make__c, where Model__c depends on the value of
+      #   # Make__c.
+      #   client.picklist_values('Automobile__c', 'Model__c', :valid_for => 'Honda')
+      #   # => [#<Force::Mash label="Civic" value="Civic">, ... ]
+      #
+      # Returns an array of Force::Mash objects.
+      def picklist_values(sobject, field, options = {})
+        PicklistValues.new(describe(sobject)['fields'], field, options)
+      end
+
+      private
+
+      class PicklistValues < Array
+
+        def initialize(fields, field, options = {})
+          @fields, @field = fields, field
+          @valid_for = options.delete(:valid_for)
+          raise "#{field} is not a dependent picklist" if @valid_for && !dependent?
+          replace(picklist_values)
+        end
+
+      private
+
+        attr_reader :fields
+
+        def picklist_values
+          if valid_for?
+            field['picklistValues'].select { |picklist_entry| valid? picklist_entry }
+          else
+            field['picklistValues']
+          end
+        end
+
+        # Returns true of the given field is dependent on another field.
+        def dependent?
+          !!field['dependentPicklist']
+        end
+
+        def valid_for?
+          !!@valid_for
+        end
+
+        def controlling_picklist
+          @_controlling_picklist ||= controlling_field['picklistValues'].find { |picklist_entry| picklist_entry['value'] == @valid_for }
+        end
+
+        def index
+          @_index ||= controlling_field['picklistValues'].index(controlling_picklist)
+        end
+
+        def controlling_field
+          @_controlling_field ||= fields.find { |f| f['name'] == field['controllerName'] }
+        end
+
+        def field
+          @_field ||= fields.find { |f| f['name'] == @field }
+        end
+
+        # Returns true if the picklist entry is valid for the controlling picklist.
+        #
+        # See http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_describesobjects_describesobjectresult.htm
+        def valid?(picklist_entry)
+          valid_for = picklist_entry['validFor'].ljust(16, 'A').unpack('m').first.unpack('q*')
+          (valid_for[index >> 3] & (0x80 >> index % 8)) != 0
+        end
+      end
+    end
+  end
+end

data/lib/force/concerns/streaming.rb

@@ -0,0 +1,31 @@
+module Force
+  module Concerns
+    module Streaming
+      # Public: Subscribe to a PushTopic
+      #
+      # channels - The name of the PushTopic channel(s) to subscribe to.
+      # block    - A block to run when a new message is received.
+      #
+      # Returns a Faye::Subscription
+      def subscribe(channels, &block)
+        faye.subscribe Array(channels).map { |channel| "/topic/#{channel}" }, &block
+      end
+
+      # Public: Faye client to use for subscribing to PushTopics
+      def faye
+        raise 'Instance URL missing. Call .authenticate! first.' unless options[:instance_url]
+        
+        @faye ||= Faye::Client.new("#{options[:instance_url]}/cometd/#{options[:api_version]}").tap do |client|
+          client.bind 'transport:down' do
+            Force.log "[COMETD DOWN]"
+            client.set_header 'Authorization', "OAuth #{authenticate!.access_token}"
+          end
+
+          client.bind 'transport:up' do
+            Force.log "[COMETD UP]"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/force/concerns/verbs.rb

@@ -0,0 +1,67 @@
+module Force
+  module Concerns
+    module Verbs
+      # Internal: Define methods to handle a verb.
+      #
+      # verbs - A list of verbs to define methods for.
+      #
+      # Examples
+      #
+      #   define_verbs :get, :post
+      #
+      # Returns nil.
+      def define_verbs(*verbs)
+        verbs.each do |verb|
+          define_verb(verb)
+          define_api_verb(verb)
+        end
+      end
+
+      # Internal: Defines a method to handle HTTP requests with the passed in
+      # verb.
+      #
+      # verb - Symbol name of the verb (e.g. :get).
+      #
+      # Examples
+      #
+      #   define_verb :get
+      #   # => get '/services/data/v24.0/sobjects'
+      #
+      # Returns nil.
+      def define_verb(verb)
+        define_method verb do |*args, &block|
+          retries = options[:authentication_retries]
+          begin
+            connection.send(verb, *args, &block)
+          rescue Force::UnauthorizedError
+            if retries > 0
+              retries -= 1
+              connection.url_prefix = options[:instance_url]
+              retry
+            end
+            
+            raise
+          end
+        end
+      end
+
+      # Internal: Defines a method to handle HTTP requests with the passed in
+      # verb to a salesforce api endpoint.
+      #
+      # verb - Symbol name of the verb (e.g. :get).
+      #
+      # Examples
+      #
+      #   define_api_verb :get
+      #   # => api_get 'sobjects'
+      #
+      # Returns nil.
+      def define_api_verb(verb)
+        define_method :"api_#{verb}" do |*args, &block|
+          args[0] = api_path(args[0])
+          send(verb, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/force/config.rb

@@ -0,0 +1,140 @@
+require 'logger'
+
+module Force
+  class << self
+    attr_writer :log
+
+    # Returns the current Configuration
+    #
+    # Example
+    #
+    #    Force.configuration.username = "username"
+    #    Force.configuration.password = "password"
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the Configuration
+    #
+    # Example
+    #
+    #    Force.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 Force.log?
+      Force.configuration.logger.send :debug, message
+    end
+  end
+
+  class Configuration
+    class Option
+      attr_reader :configuration, :name, :options
+
+      def self.define(*args)
+        new(*args).define
+      end
+
+      def initialize(configuration, name, options = {})
+        @configuration, @name, @options = configuration, name, options
+        @default = options.fetch(:default, nil)
+      end
+
+      def define
+        write_attribute
+        define_method if default_provided?
+        self
+      end
+
+    private
+    
+      attr_reader :default
+      alias_method :default_provided?, :default
+
+      def write_attribute
+        configuration.send :attr_accessor, name
+      end
+
+      def define_method
+        our_default = default
+        our_name    = name
+        configuration.send :define_method, our_name do
+          instance_variable_get(:"@#{our_name}") ||
+            instance_variable_set(:"@#{our_name}", our_default.respond_to?(:call) ? our_default.call : our_default)
+        end
+      end
+    end
+
+    class << self
+      attr_accessor :options
+
+      def option(*args)
+        option = Option.define(self, *args)
+        (self.options ||= []) << option.name
+      end
+    end
+
+    option :api_version, :default => '26.0'
+
+    # The username to use during login.
+    option :username, :default => lambda { ENV['SALESFORCE_USERNAME'] }
+
+    # The password to use during login.
+    option :password, :default => lambda { ENV['SALESFORCE_PASSWORD'] }
+
+    # The security token to use during login.
+    option :security_token, :default => lambda { ENV['SALESFORCE_SECURITY_TOKEN'] }
+
+    # The OAuth client id
+    option :client_id, :default => lambda { ENV['SALESFORCE_CLIENT_ID'] }
+
+    # The OAuth client secret
+    option :client_secret, :default => lambda { ENV['SALESFORCE_CLIENT_SECRET'] }
+
+    # Set this to true if you're authenticating with a Sandbox instance.
+    # Defaults to false.
+    option :host, :default => lambda { ENV['SALESFORCE_HOST'] || 'login.salesforce.com' }
+
+    option :oauth_token
+    option :refresh_token
+    option :instance_url
+
+    # Set this to an object that responds to read, write and fetch and all GET
+    # requests will be cached.
+    option :cache
+
+    # The number of times reauthentication should be tried before failing.
+    option :authentication_retries, :default => 3
+
+    # Set to true if you want responses from Salesforce to be gzip compressed.
+    option :compress
+
+    # Faraday request read/open timeout.
+    option :timeout
+
+    # Faraday adapter to use. Defaults to Faraday.default_adapter.
+    option :adapter, :default => lambda { Faraday.default_adapter }
+
+    option :proxy_uri, :default => lambda { ENV['PROXY_URI'] }
+
+    # A Proc that is called with the response body after a successful authentication.
+    option :authentication_callback
+
+    def logger
+      @logger ||= ::Logger.new STDOUT
+    end
+
+    def options
+      self.class.options
+    end
+  end
+end