sfdc 0.0.1 → 1.0.0

data/lib/sfdc/client/authentication.rb

@@ -0,0 +1,40 @@
+module Sfdc
+  class Client
+    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?
+          Sfdc::Middleware::Authentication::Password
+        elsif oauth_refresh?
+          Sfdc::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/sfdc/client/caching.rb

@@ -0,0 +1,26 @@
+module Sfdc
+  class Client
+    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/sfdc/client/canvas.rb

@@ -0,0 +1,12 @@
+module Sfdc
+  class Client
+    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/sfdc/client/connection.rb

@@ -0,0 +1,74 @@
+module Sfdc
+  class Client
+    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      Sfdc::Middleware::Mashify, self, @options
+          # Handles multipart file uploads for blobs.
+          builder.use      Sfdc::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      Sfdc::Middleware::Authorization, self, @options
+          # Ensures the instance url is set.
+          builder.use      Sfdc::Middleware::InstanceURL, self, @options
+          # Parses returned JSON response into a hash.
+          builder.response :json, :content_type => /\bjson$/
+          # Caches GET requests.
+          builder.use      Sfdc::Middleware::Caching, cache, @options if cache
+          # Follows 30x redirects.
+          builder.use      FaradayMiddleware::FollowRedirects
+          # Raises errors for 40x responses.
+          builder.use      Sfdc::Middleware::RaiseError
+          # Log request/responses
+          builder.use      Sfdc::Middleware::Logger, Sfdc.configuration.logger, @options if Sfdc.log?
+          # Compress/Decompress the request/response
+          builder.use      Sfdc::Middleware::Gzip, self, @options
+
+          builder.adapter  adapter
+        end
+      end
+
+      def adapter
+        Sfdc.configuration.adapter
+      end
+
+      # Internal: Faraday Connection options
+      def connection_options
+        { :request => {
+            :timeout => @options[:timeout],
+            :open_timeout => @options[:timeout] },
+          :proxy => @options[:proxy_uri]
+        }
+      end
+
+      # Internal: Returns true if the middlware stack includes the
+      # Sfdc::Middleware::Mashify middleware.
+      def mashify?
+        middleware.handlers.index(Sfdc::Middleware::Mashify)
+      end
+
+    end
+  end
+end

data/lib/sfdc/client/picklists.rb

@@ -0,0 +1,90 @@
+module Sfdc
+  class Client
+    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')
+      #   # => [#<Sfdc::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')
+      #   # => [#<Sfdc::Mash label="Civic" value="Civic">, ... ]
+      #
+      # Returns an array of Sfdc::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/sfdc/client/streaming.rb

@@ -0,0 +1,31 @@
+module Sfdc
+  class Client
+    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
+            Sfdc.log "[COMETD DOWN]"
+            client.set_header 'Authorization', "OAuth #{authenticate!.access_token}"
+          end
+          client.bind 'transport:up' do
+            Sfdc.log "[COMETD UP]"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/sfdc/client/verbs.rb

@@ -0,0 +1,68 @@
+module Sfdc
+  class Client
+    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 Sfdc::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/sfdc/collection.rb

@@ -0,0 +1,40 @@
+module Sfdc
+  class Collection
+    include Enumerable
+
+    # Given a hash and client, will create an Enumerator that will lazily
+    # request Salesforce for the next page of results.
+    def initialize(hash, client)
+      @client = client
+      @raw_page = hash
+    end
+
+    # Yield each value on each page.
+    def each
+      @raw_page['records'].each { |record| yield Sfdc::Mash.build(record, @client) }
+
+      next_page.each { |record| yield record } if has_next_page?
+    end
+
+    # Return the size of the Collection without making any additional requests.
+    def size
+      @raw_page['totalSize']
+    end
+    alias_method :length, :size
+
+    # Return the current and all of the following pages.
+    def pages
+      [self] + (has_next_page? ? next_page.pages : [])
+    end
+
+    # Returns true if there is a pointer to the next page.
+    def has_next_page?
+      !@raw_page['nextRecordsUrl'].nil?
+    end
+
+    # Returns the next page as a Sfdc::Collection if it's available, nil otherwise.
+    def next_page
+      @next_page ||= @client.get(@raw_page['nextRecordsUrl']).body if has_next_page?
+    end
+  end
+end

data/lib/sfdc/config.rb

@@ -0,0 +1,136 @@
+require 'logger'
+
+module Sfdc
+  class << self
+    attr_writer :log
+
+    # Returns the current Configuration
+    #
+    # Example
+    #
+    #    Sfdc.configuration.username = "username"
+    #    Sfdc.configuration.password = "password"
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the Configuration
+    #
+    # Example
+    #
+    #    Sfdc.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 Sfdc.log?
+      Sfdc.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 => '27.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 => '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'] }
+
+    def logger
+      @logger ||= ::Logger.new STDOUT
+    end
+
+    def options
+      self.class.options
+    end
+  end
+end