restforce 1.5.2 → 1.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85b66c52befacd436944640621d9834ba8437936
-  data.tar.gz: f64960b6e5498618a837d900d1b21ae90621b397
+  metadata.gz: cea59c76c61a80f9b37c19dd5fcf0dc65724c706
+  data.tar.gz: 803df3bf79c4f7852dd1b1f604ec394981675ac6
 SHA512:
-  metadata.gz: 4d28877615344a8a0c36112d564826b8ecdacc20aad84c4e2f4b8195cdd696bd1317eaa838d3eed87fbfc99d0dceb6efab0d4416c8f410dbc918a594bbfe0af8
-  data.tar.gz: 7fcf33ec632e6314f411e2dd4d406f2d3d1c7b98923a0d81d0387efd2a5e7d65fbb132f9c47d28b057fa334d05501876c5198424312e145d9784421311b24564
+  metadata.gz: dc604478ae597a50c0f7ca90236df153a3065f3adca8527012f28e2904e71e0ccda68adedb372e88f183598d99054776cc4e7d5ba5823af200d77bb1fbf3526b
+  data.tar.gz: 5b4fb8dff7ea15b51cb6a6e64d7e3d60985eaa46e2fdf7054725c1c3790faaacbdec056757083a47461462a3b0d6362811725dd019e767932d187c70728fc4d1

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.5.3 (Jun 26, 2015)
+
+* Fixed a bug with `update!` and `upsert!` mutating provided attributes (@timrogers)
+* Added note about thread safety to `README.md` (@epbarger)
+* Improved documentation for `select` in `README.md` (@theSteveMitchell)
+* Tweaked and improved consistency of `README.md` (@timrogers)
+* Pass through blocks given to `Restforce.new` (@jxa)
+* Add `#page_size` to `Restforce::Collection` (@theSteveMitchell)
+
 ## 1.5.2 (Apr 29, 2015)
 
 *   Better autopagination performance #141 @th7

data/README.md

@@ -37,7 +37,7 @@ Or install it yourself as:
 
 ## Usage
 
-Restforce is designed with flexibility and ease of use in mind. By default, all api calls will
+Restforce is designed with flexibility and ease of use in mind. By default, all API calls will
 return [Hashie::Mash](https://github.com/intridea/hashie/tree/v1.2.0) objects,
 so you can do things like `client.query('select Id, (select Name from Children__r) from Account').Children__r.first.Name`.
 
@@ -52,6 +52,8 @@ If you're using the gem to interact with a single org (maybe you're building som
 salesforce integration internally?) then you should use the username/password
 authentication method.
 
+It is also important to note that the client object should not be reused across different threads, otherwise you may encounter thread-safety issues.
+
 #### OAuth token authentication
 
 ```ruby
@@ -60,7 +62,7 @@ client = Restforce.new :oauth_token => 'oauth token',
 ```
 
 Although the above will work, you'll probably want to take advantage of the
-(re)authentication middleware by specifying a refresh token, client id and client secret:
+(re)authentication middleware by specifying a `refresh_token`, `client_id` and `client_secret`:
 
 ```ruby
 client = Restforce.new :oauth_token => 'oauth token',
@@ -82,7 +84,7 @@ client = Restforce.new :username => 'foo',
   :client_secret  => 'client_secret'
 ```
 
-You can also set the username, password, security token, client id and client
+You can also set the username, password, security token, client ID and client
 secret in environment variables:
 
 ```bash
@@ -96,9 +98,10 @@ export SALESFORCE_CLIENT_SECRET="client secret"
 ```ruby
 client = Restforce.new
 ```
+
 ### Proxy Support
 
-You can specify a http proxy using the :proxy_uri option, as follows:
+You can specify a HTTP proxy using the `proxy_uri` option, as follows, or by setting the `PROXY_URI` environment variable:
 
 ```ruby
 client = Restforce.new :username => 'foo',
@@ -108,7 +111,8 @@ client = Restforce.new :username => 'foo',
   :client_secret  => 'client_secret',
   :proxy_uri      => 'http://proxy.example.com:123'
 ```
-This paramter also will accept 'http://user@password:proxy.example.com:123' or using the environemnt variable PROXY_URI.
+
+You may specify a username and password for the proxy with a URL along the lines of 'http://user@password:proxy.example.com:123'.
 
 #### Sandbox Orgs
 
@@ -118,11 +122,11 @@ 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.
+The host can also be set with the environment variable `SALESFORCE_HOST`.
 
 #### Global configuration
 
-You can set any of the options passed into Restforce.new globally:
+You can set any of the options passed into `Restforce.new` globally:
 
 ```ruby
 Restforce.configure do |config|
@@ -133,8 +137,8 @@ end
 
 ### Bang! methods
 
-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
+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
 non-bang methods will return false in the event that an exception is raised. This
 works similarly to ActiveRecord.
@@ -176,14 +180,12 @@ client.find('Account', '1234', 'Some_External_Id_Field__c')
 
 ### select
 
-```ruby
-client.select('Account', '001D000000INjVe', ["Id"])
-# => {"attributes" : {"type" : "Account","url" : "/services/data/v20.0/sobjects/Account/001D000000INjVe"},
-#   "Id" : "001D000000INjVe"}
+`select` allows the fetching of a specific list of fields from a single object.  It requires an `external_id` lookup, but is often much faster than an arbitrary query.
 
+```ruby
+# Select the `Id` column from a record with `Some_External_Id_Field__c` set to '001D000000INjVe'
 client.select('Account', '001D000000INjVe', ["Id"], 'Some_External_Id_Field__c')
-# => {"attributes" : {"type" : "Account","url" : "/services/data/v20.0/sobjects/Account/Some_External_Id_Field__c/001D000000INjVe"},
-#   "Id" : "003F000000BGIn3"}
+# => {"attributes" : {"type" : "Account","url" : "/services/data/v20.0/sobjects/Account/Some_External_Id_Field__c/001D000000INjVe"}, "Id" : "003F000000BGIn3"}
 ```
 
 ### search
@@ -193,7 +195,7 @@ client.select('Account', '001D000000INjVe', ["Id"], 'Some_External_Id_Field__c')
 client.search('FIND {bar}')
 # => #<Restforce::Collection >
 
-# Find accounts match the term 'genepoint' and return the Name field
+# Find accounts matching the term 'genepoint' and return the `Name` field
 client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
 # => ['GenePoint']
 ```
@@ -209,7 +211,7 @@ client.create('Account', Name: 'Foobar Inc.')
 ### update
 
 ```ruby
-# Update the Account with Id '0016000000MRatd'
+# Update the Account with `Id` '0016000000MRatd'
 client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
 # => true
 ```
@@ -217,14 +219,14 @@ client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
 ### upsert
 
 ```ruby
-# Update the record with external ID of 12
+# Update the record with external `External__c` external ID set to '12'
 client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
 ```
 
 ### destroy
 
 ```ruby
-# Delete the Account with Id '0016000000MRatd'
+# Delete the Account with `Id` '0016000000MRatd'
 client.destroy('Account', '0016000000MRatd')
 # => true
 ```
@@ -232,11 +234,11 @@ client.destroy('Account', '0016000000MRatd')
 ### describe
 
 ```ruby
-# get the global describe for all sobjects
+# Get the global describe for all sobjects
 client.describe
 # => { ... }
 
-# get the describe for the Account object
+# Get the describe for the Account object
 client.describe('Account')
 # => { ... }
 ```
@@ -244,11 +246,11 @@ client.describe('Account')
 ### describe_layouts
 
 ```ruby
-# get layouts for an sobject type
+# Get layouts for an sobject type
 client.describe_layout('Account')
 # => { ... }
 
-# get the details for a specific layout
+# Get the details for a specific layout by its ID
 client.describe_layouts('Account', '012E0000000RHEp')
 # => { ... }
 ```
@@ -257,12 +259,13 @@ client.describe_layouts('Account', '012E0000000RHEp')
 
 
 ```ruby
+# Fetch picklist value for Account's `Type` field
 client.picklist_values('Account', 'Type')
 # => [#<Restforce::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.
+# `Model__c` and `Make__c`, where options for `Model__c` depends on the value of
+# `Make__c`.
 client.picklist_values('Automobile__c', 'Model__c', :valid_for => 'Honda')
 # => [#<Restforce::Mash label="Civic" value="Civic">, ... ]
 ```
@@ -270,7 +273,7 @@ client.picklist_values('Automobile__c', 'Model__c', :valid_for => 'Honda')
 ### user_info
 
 ```ruby
-# get info about the logged-in user
+# Get info about the logged-in user
 client.user_info
 # => #<Restforce::Mash active=true display_name="Chatty Sassy" email="user@example.com" ... >
 ```

data/lib/restforce.rb

@@ -44,16 +44,16 @@ module Restforce
     # Alias for Restforce::Data::Client.new
     #
     # Shamelessly pulled from https://github.com/pengwynn/octokit/blob/master/lib/octokit.rb
-    def new(*args)
-      data(*args)
+    def new(*args, &block)
+      data(*args, &block)
     end
 
-    def data(*args)
-      Restforce::Data::Client.new(*args)
+    def data(*args, &block)
+      Restforce::Data::Client.new(*args, &block)
     end
 
-    def tooling(*args)
-      Restforce::Tooling::Client.new(*args)
+    def tooling(*args, &block)
+      Restforce::Tooling::Client.new(*args, &block)
     end
 
     # Helper for decoding signed requests.

data/lib/restforce/collection.rb

@@ -20,6 +20,10 @@ module Restforce
       end
     end
 
+    # Return the size of each page in the collection
+    def page_size
+      @raw_page['records'].size
+    end
 
     # Return the size of the Collection without making any additional requests.
     def size

data/lib/restforce/concerns/api.rb

@@ -220,9 +220,10 @@ module Restforce
       # 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' })
+        id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.downcase == 'id' }, nil)
         raise ArgumentError, 'Id field missing from attrs.' unless id
-        api_patch "sobjects/#{sobject}/#{id}", attrs
+        attrs_without_id = attrs.reject { |k, v| k.to_s.downcase == "id" }
+        api_patch "sobjects/#{sobject}/#{id}", attrs_without_id
         true
       end
 
@@ -261,8 +262,9 @@ module Restforce
       # 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
+        external_id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.downcase == field.to_s.downcase }, nil)
+        attrs_without_field = attrs.reject { |k, v| k.to_s.downcase == field.to_s.downcase }
+        response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs_without_field
         (response.body && response.body['id']) ? response.body['id'] : true
       end
 
@@ -319,13 +321,13 @@ module Restforce
       # id      - The id of the record. If field is specified, id should be the id
       #           of the external field.
       # select  - A String array denoting the fields to select.  If nil or empty array
-      #           is passed, all fields are selected.  
+      #           is passed, all fields are selected.
       # field   - External ID field to use (default: nil).
       #
       def select(sobject, id, select, field=nil)
         path = field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}"
         path << "?fields=#{select.join(",")}" if select && select.any?
-        
+
         api_get(path).body
       end
 

data/lib/restforce/config.rb

@@ -127,6 +127,7 @@ module Restforce
     # Faraday adapter to use. Defaults to Faraday.default_adapter.
     option :adapter, :default => lambda { Faraday.default_adapter }
 
+    # TODO: Rename this to `SALESFORCE_PROXY_URI` in next major version
     option :proxy_uri, :default => lambda { ENV['PROXY_URI'] }
 
     # A Proc that is called with the response body after a successful authentication.

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = '1.5.2'
+  VERSION = '1.5.3'
 end

data/spec/unit/collection_spec.rb

@@ -13,6 +13,7 @@ describe Restforce::Collection do
       its(:size)           { should eq 1 }
       its(:has_next_page?) { should be_false }
       it                   { should have_client client }
+      its(:page_size)      { should eq 1 }
 
       describe 'each record' do
         it { should be_all { |record| expect(record).to be_a Restforce::SObject } }
@@ -34,6 +35,7 @@ describe Restforce::Collection do
         its(:first) { should be_a Restforce::SObject }
         its(:current_page) { should be_a Array }
         its(:current_page) { should have(1).element }
+        its(:page_size)    { should eq 1 }
       end
 
       context 'when all of the values are being requested' do

data/spec/unit/concerns/api_spec.rb

@@ -177,11 +177,11 @@ describe Restforce::Concerns::API do
     subject(:result) { client.update!(sobject, attrs) }
 
     context 'when the id field is present' do
-      let(:attrs) { { :id => '1234' } }
+      let(:attrs) { { :id => '1234', :StageName => "Call Scheduled" } }
 
       it 'sends an HTTP PATCH, and returns true' do
         client.should_receive(:api_patch).
-          with('sobjects/Whizbang/1234', attrs)
+          with('sobjects/Whizbang/1234', { :StageName => "Call Scheduled" })
         expect(result).to be_true
       end
     end

data/spec/unit/config_spec.rb

@@ -96,4 +96,14 @@ describe Restforce do
       end
     end
   end
+
+  describe '.new' do
+    it 'calls its block' do
+      checker = double(:block_checker)
+      expect(checker).to receive(:check!).once
+      Restforce.new do |builder|
+        checker.check!
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.5.3
 platform: ruby
 authors:
 - Eric J. Holmes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-29 00:00:00.000000000 Z
+date: 2015-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -272,7 +272,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.7
 signing_key: 
 specification_version: 4
 summary: A lightweight ruby client for the Salesforce REST api.