restforce 1.3.0 → 1.4.0

data/.travis.yml

@@ -3,6 +3,7 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - 2.0.0
   - jruby-18mode
   - jruby-19mode
   - ree

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.4.0 (Jun 9, 2013)
+
+*   Added support for the tooling API.
+*   Fixed a bug with EMSynchrony adapter.
+*   Added proxy support.
+
 ## 1.3.0 (Apr 6, 2013)
 
 *   Added support for lazily traversing paginated collections #61 by @nahiluhmot.
@@ -59,7 +65,7 @@
 *   The http connection read/open timeout is now configurabled.
 
     Example:
-    
+
         Restforce.configure do |config|
           config.timeout = 300
         end

data/Gemfile

@@ -5,3 +5,7 @@ gemspec
 
 gem 'rake'
 gem 'jruby-openssl', :platforms => :jruby
+
+group :development do
+  gem 'guard-rspec'
+end

data/Guardfile

@@ -0,0 +1,11 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', all_on_start: false, all_after_pass: false do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  watch(%r{^lib/restforce/(.+)\.rb$})                 { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch(%r{^lib/restforce/(.+)\.rb$})                 { |m| "spec/integration/#{m[1]}_spec.rb" }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+end

data/README.md

@@ -77,7 +77,7 @@ If you prefer to use a username and password to authenticate:
 ```ruby
 client = Restforce.new :username => 'foo',
   :password       => 'bar',
-  :security_token => 'security token'
+  :security_token => 'security token',
   :client_id      => 'client_id',
   :client_secret  => 'client_secret'
 ```
@@ -103,7 +103,7 @@ You can specify a http proxy using the :proxy_uri option, as follows:
 ```ruby
 client = Restforce.new :username => 'foo',
   :password       => 'bar',
-  :security_token => 'security token'
+  :security_token => 'security token',
   :client_id      => 'client_id',
   :client_secret  => 'client_secret',
   :proxy_uri      => 'http://proxy.example.com:123'
@@ -118,6 +118,7 @@ You can connect to sandbox orgs by specifying a host. The default host is
 ```ruby
 client = Restforce.new :host => 'test.salesforce.com'
 ```
+The host can also be set with the environment variable SALESFORCE_HOST.
 
 #### Global configuration
 
@@ -132,9 +133,9 @@ end
 
 ### Bang! methods
 
-All the CRUD methods (create, update, upsert, destroy) have equivalent methods with 
+All the CRUD methods (create, update, upsert, destroy) have equivalent methods with
 a ! at the end (create!, update!, upsert!, destroy!), which can be used if you need
-to do some custom error handling. The bang methods will raise exceptions, while the 
+to do some custom error handling. The bang methods will raise exceptions, while the
 non-bang methods will return false in the event that an exception is raised. This
 works similarly to ActiveRecord.
 
@@ -146,7 +147,7 @@ works similarly to ActiveRecord.
 accounts = client.query("select Id, Something__c from Account where Id = 'someid'")
 # => #<Restforce::Collection >
 
-account = records.first
+account = accounts.first
 # => #<Restforce::SObject >
 
 account.sobject_type
@@ -411,9 +412,10 @@ Restforce in a rails app, you can setup custom reporting to
 [Librato](https://github.com/librato/librato-rails) using ActiveSupport::Notifications:
 
 ```ruby
-client = Restforce.new
-client.middleware.insert_after Restforce::Middleware::InstanceURL,
-  FaradayMiddleware::Instrumentation, name: 'request.salesforce'
+client = Restforce.new do |builder|
+  builder.insert_after Restforce::Middleware::InstanceURL,
+    FaradayMiddleware::Instrumentation, name: 'request.salesforce'
+end
 
 # config/initializers/notifications.rb
 ActiveSupport::Notifications.subscribe('request.salesforce') do |*args|
@@ -427,6 +429,15 @@ end
 
 You can use Restforce to decode signed requests from Salesforce. See [the example app](https://gist.github.com/4052312).
 
+## Tooling API
+
+To use the [Tooling API](http://www.salesforce.com/us/developer/docs/api_toolingpre/api_tooling.pdf),
+call `Restforce.tooling` instead of `Restforce.new`:
+
+```ruby
+client = Restforce.tooling(...)
+```
+
 ## Contributing
 
 1. Fork it

data/lib/restforce.rb

@@ -6,24 +6,54 @@ require 'restforce/version'
 require 'restforce/config'
 
 module Restforce
-  autoload :SignedRequest, 'restforce/signed_request'
-  autoload :Collection,    'restforce/collection'
-  autoload :Middleware,    'restforce/middleware'
-  autoload :Attachment,    'restforce/attachment'
-  autoload :UploadIO,      'restforce/upload_io'
-  autoload :SObject,       'restforce/sobject'
-  autoload :Client,        'restforce/client'
-  autoload :Mash,          'restforce/mash'
-
-  AuthenticationError = Class.new(StandardError)
-  UnauthorizedError   = Class.new(StandardError)
+  autoload :AbstractClient, 'restforce/abstract_client'
+  autoload :SignedRequest,  'restforce/signed_request'
+  autoload :Collection,     'restforce/collection'
+  autoload :Middleware,     'restforce/middleware'
+  autoload :Attachment,     'restforce/attachment'
+  autoload :UploadIO,       'restforce/upload_io'
+  autoload :SObject,        'restforce/sobject'
+  autoload :Client,         'restforce/client'
+  autoload :Mash,           'restforce/mash'
+
+  module Concerns
+    autoload :Authentication, 'restforce/concerns/authentication'
+    autoload :Connection,     'restforce/concerns/connection'
+    autoload :Picklists,      'restforce/concerns/picklists'
+    autoload :Streaming,      'restforce/concerns/streaming'
+    autoload :Caching,        'restforce/concerns/caching'
+    autoload :Canvas,         'restforce/concerns/canvas'
+    autoload :Verbs,          'restforce/concerns/verbs'
+    autoload :Base,           'restforce/concerns/base'
+    autoload :API,            'restforce/concerns/api'
+  end
+
+  module Data
+    autoload :Client, 'restforce/data/client'
+  end
+
+  module Tooling
+    autoload :Client, 'restforce/tooling/client'
+  end
+
+  Error               = Class.new(StandardError)
+  AuthenticationError = Class.new(Error)
+  UnauthorizedError   = Class.new(Error)
 
   class << self
-    # Alias for Restforce::Client.new
+    # Alias for Restforce::Data::Client.new
     #
     # Shamelessly pulled from https://github.com/pengwynn/octokit/blob/master/lib/octokit.rb
-    def new(options = {})
-      Restforce::Client.new(options)
+    def new(*args)
+      data(*args)
+    end
+
+    def data(*args)
+      Restforce::Data::Client.new(*args)
+    end
+
+    def tooling(*args)
+      Restforce::Tooling::Client.new(*args)
     end
 
     # Helper for decoding signed requests.

data/lib/restforce/abstract_client.rb

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

data/lib/restforce/client.rb

@@ -1,97 +1,3 @@
-require 'restforce/client/connection'
-require 'restforce/client/authentication'
-require 'restforce/client/streaming'
-require 'restforce/client/picklists'
-require 'restforce/client/caching'
-require 'restforce/client/canvas'
-require 'restforce/client/api'
-
 module Restforce
-  class Client
-    include Restforce::Client::Connection
-    include Restforce::Client::Authentication
-    include Restforce::Client::Streaming
-    include Restforce::Client::Picklists
-    include Restforce::Client::Caching
-    include Restforce::Client::Canvas
-    include Restforce::Client::API
-
-    # Public: Creates a new client instance
-    #
-    # opts - 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'
-    #
-    # Examples
-    #
-    #   # Initialize a new client using password authentication:
-    #   Restforce::Client.new :username => 'user',
-    #     :password => 'pass',
-    #     :security_token => 'security token',
-    #     :client_id => 'client id',
-    #     :client_secret => 'client secret'
-    #
-    #   # Initialize a new client using oauth authentication:
-    #   Restforce::Client.new :oauth_token => 'access token',
-    #     :refresh_token => 'refresh token',
-    #     :instance_url => 'https://na1.salesforce.com',
-    #     :client_id => 'client id',
-    #     :client_secret => 'client secret'
-    #
-    #   # Initialize a new client without using any authentication middleware:
-    #   Restforce::Client.new :oauth_token => 'access token',
-    #     :instance_url => 'https://na1.salesforce.com'
-    #
-    def initialize(opts = {})
-      raise 'Please specify a hash of options' unless opts.is_a?(Hash)
-      @options = Hash[Restforce.configuration.options.map { |option| [option, Restforce.configuration.send(option)] }]
-      @options.merge! opts
-    end
-
-    def instance_url
-      authenticate! unless @options[:instance_url]
-      @options[:instance_url]
-    end
-
-    # Public: Returns a url to the resource.
-    #
-    # resource - A record that responds to to_sparam or a String/Fixnum.
-    #
-    # Returns the url to the resource.
-    def url(resource)
-      "#{instance_url}/#{(resource.respond_to?(:to_sparam) ? resource.to_sparam : resource)}"
-    end
-
-    def inspect
-      "#<#{self.class} @options=#{@options.inspect}>"
-    end
-  end
+  Client = Data::Client
 end

data/lib/restforce/{client → concerns}/api.rb

@@ -1,9 +1,9 @@
-require 'restforce/client/verbs'
+require 'restforce/concerns/verbs'
 
 module Restforce
-  class Client
+  module Concerns
     module API
-      extend Restforce::Client::Verbs
+      extend Restforce::Concerns::Verbs
 
       # Public: Helper methods for performing arbitrary actions against the API using
       # various HTTP verbs.
@@ -41,7 +41,7 @@ module Restforce
       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).
@@ -76,7 +76,7 @@ module Restforce
       def org_id
         query('select id from Organization').first['Id']
       end
-      
+
       # Public: Executs a SOQL query and returns the result.
       #
       # soql - A SOQL expression.
@@ -93,7 +93,7 @@ module Restforce
         response = api_get 'query', :q => soql
         mashify? ? response.body : response.body['records']
       end
-      
+
       # Public: Perform a SOSL search
       #
       # sosl - A SOSL expression.
@@ -113,7 +113,7 @@ module Restforce
       def search(sosl)
         api_get('search', :q => sosl).body
       end
-      
+
       # Public: Insert a new record.
       #
       # sobject - String name of the sobject.
@@ -184,7 +184,7 @@ module Restforce
       # 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 'Id field missing.' unless id
+        raise ArgumentError, 'Id field missing from attrs.' unless id
         api_patch "sobjects/#{sobject}/#{id}", attrs
         true
       end
@@ -285,7 +285,7 @@ module Restforce
       #   api_path('sobjects')
       #   # => '/services/data/v24.0/sobjects'
       def api_path(path)
-        "/services/data/v#{@options[:api_version]}/#{path}"
+        "/services/data/v#{options[:api_version]}/#{path}"
       end
 
       # Internal: Errors that should be rescued from in non-bang methods

data/lib/restforce/{client → concerns}/authentication.rb

@@ -1,11 +1,11 @@
 module Restforce
-  class Client
+  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 = authentication_middleware.new nil, self, options
         middleware.authenticate!
       end
 
@@ -21,18 +21,18 @@ module Restforce
       # 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]
+        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]
+        options[:refresh_token] &&
+          options[:client_id] &&
+          options[:client_secret]
       end
 
     end

data/lib/restforce/concerns/base.rb

@@ -0,0 +1,58 @@
+module Restforce
+  module Concerns
+    module Base
+
+      attr_reader :options
+
+      # Public: Creates a new client instance
+      #
+      # opts - 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'
+      def initialize(opts = {})
+        raise ArgumentError, 'Please specify a hash of options' unless opts.is_a?(Hash)
+        @options = Hash[Restforce.configuration.options.map { |option| [option, Restforce.configuration.send(option)] }]
+        @options.merge! opts
+        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