force 0.0.1

data/force.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/force/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name          = "force"
+  s.version       = Force::VERSION
+  s.authors       = ["Eric J. Holmes", "Mattt Thompson"]
+  s.email         = ["eric@ejholmes.net", "mattt@heroku.com"]
+  s.description   = "A lightweight ruby client for the Salesforce REST api."
+  s.summary       = "A lightweight ruby client for the Salesforce REST api."
+  s.homepage      = "https://github.com/heroku/force"
+
+  s.files         = Dir["./**/*"].reject { |file| file =~ /\.\/(bin|example|log|pkg|script|spec|test|vendor)/ }
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'faraday', '~> 0.8.4'
+  s.add_dependency 'faraday_middleware', '>= 0.8.8'
+  s.add_dependency 'json', ['>= 1.7.5', '< 1.9.0']
+  s.add_dependency 'hashie', ['>= 1.2.0', '< 2.1']
+
+  s.add_development_dependency 'rspec', '~> 2.14.0'
+  s.add_development_dependency 'webmock', '~> 1.13.0'
+  s.add_development_dependency 'simplecov', '~> 0.7.1'
+  s.add_development_dependency 'faye' unless RUBY_PLATFORM == 'java'
+end

data/lib/force.rb

@@ -0,0 +1,74 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'json'
+
+require 'force/version'
+require 'force/config'
+
+module Force
+  autoload :AbstractClient, 'force/abstract_client'
+  autoload :SignedRequest,  'force/signed_request'
+  autoload :Collection,     'force/collection'
+  autoload :Middleware,     'force/middleware'
+  autoload :Attachment,     'force/attachment'
+  autoload :UploadIO,       'force/upload_io'
+  autoload :SObject,        'force/sobject'
+  autoload :Client,         'force/client'
+  autoload :Mash,           'force/mash'
+
+  module Concerns
+    autoload :Authentication, 'force/concerns/authentication'
+    autoload :Connection,     'force/concerns/connection'
+    autoload :Picklists,      'force/concerns/picklists'
+    autoload :Streaming,      'force/concerns/streaming'
+    autoload :Caching,        'force/concerns/caching'
+    autoload :Canvas,         'force/concerns/canvas'
+    autoload :Verbs,          'force/concerns/verbs'
+    autoload :Base,           'force/concerns/base'
+    autoload :API,            'force/concerns/api'
+  end
+
+  module Data
+    autoload :Client, 'force/data/client'
+  end
+
+  module Tooling
+    autoload :Client, 'force/tooling/client'
+  end
+
+  Error               = Class.new(StandardError)
+  AuthenticationError = Class.new(Error)
+  UnauthorizedError   = Class.new(Error)
+
+  class << self
+    # Alias for Force::Data::Client.new
+    #
+    # Shamelessly pulled from https://github.com/pengwynn/octokit/blob/master/lib/octokit.rb
+    def new(*args)
+      data(*args)
+    end
+
+    def data(*args)
+      Force::Data::Client.new(*args)
+    end
+
+    def tooling(*args)
+      Force::Tooling::Client.new(*args)
+    end
+
+    # Helper for decoding signed requests.
+    def decode_signed_request(*args)
+      SignedRequest.decode(*args)
+    end
+  end
+
+  # Add .tap method in Ruby 1.8
+  module CoreExtensions
+    def tap
+      yield self
+      self
+    end
+  end
+  
+  Object.send :include, Force::CoreExtensions unless Object.respond_to? :tap
+end

data/lib/force/abstract_client.rb

@@ -0,0 +1,9 @@
+module Force
+  class AbstractClient
+    include Force::Concerns::Base
+    include Force::Concerns::Connection
+    include Force::Concerns::Authentication
+    include Force::Concerns::Caching
+    include Force::Concerns::API
+  end
+end

data/lib/force/attachment.rb

@@ -0,0 +1,21 @@
+module Force
+  class Attachment < Force::SObject
+    # Public: Returns the body of the attachment.
+    #
+    # Examples
+    #
+    #   attachment = client.query('select Id, Name, Body from Attachment').first
+    #   File.open(attachment.Name, 'wb') { |f| f.write(attachment.Body) }
+    def Body
+      ensure_id && ensure_body
+      @client.get(super).body
+    end
+
+  private
+
+    def ensure_body
+      return true if self.Body?
+      raise 'You need to query the Body for the record first.'
+    end
+  end
+end

data/lib/force/client.rb

@@ -0,0 +1,3 @@
+module Force
+  Client = Data::Client
+end

data/lib/force/collection.rb

@@ -0,0 +1,45 @@
+module Force
+  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 Force::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 array of the elements on the current page
+    def current_page
+      first(@raw_page['records'].size)
+    end
+
+    # 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 Force::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/force/concerns/api.rb

@@ -0,0 +1,321 @@
+require 'force/concerns/verbs'
+
+module Force
+  module Concerns
+    module API
+      extend Force::Concerns::Verbs
+
+      # Public: Helper methods for performing arbitrary actions against the API using
+      # various HTTP verbs.
+      #
+      # Examples
+      #
+      #   # Perform a get request
+      #   client.get '/services/data/v24.0/sobjects'
+      #   client.api_get 'sobjects'
+      #
+      #   # Perform a post request
+      #   client.post '/services/data/v24.0/sobjects/Account', { ... }
+      #   client.api_post 'sobjects/Account', { ... }
+      #
+      #   # Perform a put request
+      #   client.put '/services/data/v24.0/sobjects/Account/001D000000INjVe', { ... }
+      #   client.api_put 'sobjects/Account/001D000000INjVe', { ... }
+      #
+      #   # Perform a delete request
+      #   client.delete '/services/data/v24.0/sobjects/Account/001D000000INjVe'
+      #   client.api_delete 'sobjects/Account/001D000000INjVe'
+      #
+      # Returns the Faraday::Response.
+      define_verbs :get, :post, :put, :delete, :patch, :head
+
+      # Public: Get the names of all sobjects on the org.
+      #
+      # Examples
+      #
+      #   # get the names of all sobjects on the org
+      #   client.list_sobjects
+      #   # => ['Account', 'Lead', ... ]
+      #
+      # Returns an Array of String names for each SObject.
+      def list_sobjects
+        describe.collect { |sobject| sobject['name'] }
+      end
+
+      # Public: Returns a detailed describe result for the specified sobject
+      #
+      # sobject - Stringish name of the sobject (default: nil).
+      #
+      # Examples
+      #
+      #   # get the global describe for all sobjects
+      #   client.describe
+      #   # => { ... }
+      #
+      #   # get the describe for the Account object
+      #   client.describe('Account')
+      #   # => { ... }
+      #
+      # Returns the Hash representation of the describe call.
+      def describe(sobject = nil)
+        if sobject
+          api_get("sobjects/#{sobject.to_s}/describe").body
+        else
+          api_get('sobjects').body['sobjects']
+        end
+      end
+
+      # Public: Returns a detailed description of the Page Layout for the
+      # specified sobject type, or URIs for layouts if the sobject has
+      # multiple Record Types.
+      #
+      # This resource was introduced in version 28.0.
+      #
+      # Examples:
+      #  # get the layouts for the sobject
+      #  client.describe_layouts('Account')
+      #  # => { ... }
+      #
+      #  # get the layout for the specified Id for the sobject
+      #  client.describe_layouts('Account', '012E0000000RHEp')
+      #  # => { ... }
+      #
+      # Returns the Hash representation of the describe_layouts result
+      def describe_layouts(sobject, layout_id = nil)
+        if layout_id
+          api_get("sobjects/#{sobject.to_s}/describe/layouts/#{layout_id}").body
+        else
+          api_get("sobjects/#{sobject.to_s}/describe/layouts").body
+        end
+      end
+
+      # Public: Get the current organization's Id.
+      #
+      # Examples
+      #
+      #   client.org_id
+      #   # => '00Dx0000000BV7z'
+      #
+      # Returns the String organization Id
+      def org_id
+        query('select id from Organization').first['Id']
+      end
+
+      # Public: Executs a SOQL query and returns the result.
+      #
+      # soql - A SOQL expression.
+      #
+      # Examples
+      #
+      #   # Find the names of all Accounts
+      #   client.query('select Name from Account').map(&:Name)
+      #   # => ['Foo Bar Inc.', 'Whizbang Corp']
+      #
+      # Returns a Force::Collection if Force.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Force.configuration.mashify is false.
+      def query(soql)
+        response = api_get 'query', :q => soql
+        mashify? ? response.body : response.body['records']
+      end
+
+      # Public: Perform a SOSL search
+      #
+      # sosl - A SOSL expression.
+      #
+      # Examples
+      #
+      #   # Find all occurrences of 'bar'
+      #   client.search('FIND {bar}')
+      #   # => #<Force::Collection >
+      #
+      #   # Find accounts match the term 'genepoint' and return the Name field
+      #   client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
+      #   # => ['GenePoint']
+      #
+      # Returns a Force::Collection if Force.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Force.configuration.mashify is false.
+      def search(sosl)
+        api_get('search', :q => sosl).body
+      end
+
+      # Public: Insert a new record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new account
+      #   client.create('Account', Name: 'Foobar Inc.')
+      #   # => '0016000000MRatd'
+      #
+      # Returns the String Id of the newly created sobject.
+      # Returns false if something bad happens.
+      def create(*args)
+        create!(*args)
+      rescue *exceptions
+        false
+      end
+      alias_method :insert, :create
+
+      # Public: Insert a new record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new account
+      #   client.create!('Account', Name: 'Foobar Inc.')
+      #   # => '0016000000MRatd'
+      #
+      # Returns the String Id of the newly created sobject.
+      # Raises exceptions if an error is returned from Salesforce.
+      def create!(sobject, attrs)
+        api_post("sobjects/#{sobject}", attrs).body['id']
+      end
+      alias_method :insert!, :create!
+
+      # Public: Update a record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the Account with Id '0016000000MRatd'
+      #   client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+      #
+      # Returns true if the sobject was successfully updated.
+      # Returns false if there was an error.
+      def update(*args)
+        update!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Update a record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the Account with Id '0016000000MRatd'
+      #   client.update!('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+      #
+      # Returns true if the sobject was successfully updated.
+      # Raises an exception if an error is returned from Salesforce.
+      def update!(sobject, attrs)
+        id = attrs.delete(attrs.keys.find { |k| k.to_s.downcase == 'id' })
+        raise ArgumentError, 'Id field missing from attrs.' unless id
+        api_patch "sobjects/#{sobject}/#{id}", attrs
+        true
+      end
+
+      # Public: Update or create a record based on an external ID
+      #
+      # sobject - The name of the sobject to created.
+      # field   - The name of the external Id field to match against.
+      # attrs   - Hash of attributes for the record.
+      #
+      # Examples
+      #
+      #   # Update the record with external ID of 12
+      #   client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
+      #
+      # Returns true if the record was found and updated.
+      # Returns the Id of the newly created record if the record was created.
+      # Returns false if something bad happens.
+      def upsert(*args)
+        upsert!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Update or create a record based on an external ID
+      #
+      # sobject - The name of the sobject to created.
+      # field   - The name of the external Id field to match against.
+      # attrs   - Hash of attributes for the record.
+      #
+      # Examples
+      #
+      #   # Update the record with external ID of 12
+      #   client.upsert!('Account', 'External__c', External__c: 12, Name: 'Foobar')
+      #
+      # Returns true if the record was found and updated.
+      # Returns the Id of the newly created record if the record was created.
+      # Raises an exception if an error is returned from Salesforce.
+      def upsert!(sobject, field, attrs)
+        external_id = attrs.delete(attrs.keys.find { |k| k.to_s.downcase == field.to_s.downcase })
+        response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs
+        (response.body && response.body['id']) ? response.body['id'] : true
+      end
+
+      # Public: Delete a record.
+      #
+      # sobject - String name of the sobject.
+      # id      - The Salesforce ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the Account with Id '0016000000MRatd'
+      #   client.destroy('Account', '0016000000MRatd')
+      #
+      # Returns true if the sobject was successfully deleted.
+      # Returns false if an error is returned from Salesforce.
+      def destroy(*args)
+        destroy!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Delete a record.
+      #
+      # sobject - String name of the sobject.
+      # id      - The Salesforce ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the Account with Id '0016000000MRatd'
+      #   client.destroy('Account', '0016000000MRatd')
+      #
+      # Returns true of the sobject was successfully deleted.
+      # Raises an exception if an error is returned from Salesforce.
+      def destroy!(sobject, id)
+        api_delete "sobjects/#{sobject}/#{id}"
+        true
+      end
+
+      # Public: Finds a single record and returns all fields.
+      #
+      # sobject - The String name of the sobject.
+      # id      - The id of the record. If field is specified, id should be the id
+      #           of the external field.
+      # field   - External ID field to use (default: nil).
+      #
+      # Returns the Force::SObject sobject record.
+      def find(sobject, id, field=nil)
+        api_get(field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}").body
+      end
+
+      private
+
+      # Internal: Returns a path to an api endpoint
+      #
+      # Examples
+      #
+      #   api_path('sobjects')
+      #   # => '/services/data/v24.0/sobjects'
+      def api_path(path)
+        "/services/data/v#{options[:api_version]}/#{path}"
+      end
+
+      # Internal: Errors that should be rescued from in non-bang methods
+      def exceptions
+        [Faraday::Error::ClientError]
+      end
+    end
+  end
+end