sfdc 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4a336e27a5dc02b776c7d3898a80ff1d51c0020
-  data.tar.gz: d7c5c2eb05b464a0da43d7d92cd014831446c5b2
+  metadata.gz: c0777cd578c83c00d2e82e11381cf201beaa77fc
+  data.tar.gz: 53c8f26b935d9417311c2407a7e7e65f3a7d0531
 SHA512:
-  metadata.gz: 3081785e27bc7dbd8d55dd481c179d35bee99f420912fc05178a8ee8e08183d0aebb47ab44507504b0710ebdb0d9b3113c21c8fdc073f3802718b4500ce75567
-  data.tar.gz: 27e4897d37ab690d6faa5c82dd1a5c05f83fe1c196de559203f3a1a27ab65d89a734c17aafbad0021d490759b1a80d94bbd133df3afad4f538ddbd9fd5f99d4a
+  metadata.gz: 73424a61e0a4dc7cb3782757e2c016a1d487a52d53c3b4c0817089b30b68f8db3cb02304275bbdd131a54ca2b2fa1d15c54efd3e70d6580f8b0aff6c2e792e11
+  data.tar.gz: 8f010622a2019db48a46fcd766c2046aa059846885cb6eab6db34b340380f90fa2393c3bdfe58e53c1d62bffc1bf70f3429d1fcf8da1e81f598343564f91ac7c

data/CHANGELOG.md

@@ -0,0 +1,96 @@
+## 1.4.1 (Jun 18, 2013)
+
+*   Fixed a bug with HTTP 413 responses #75 @patronmanager
+
+## 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.
+
+## 1.2.0 (Mar 30, 2013)
+
+*   Added support for proxies #60 by @wazoo.
+
+## 1.1.0 (Mar 3, 2013)
+
+*   Added ability to download attachments easily.
+
+    Example
+
+        attachment = client.query('select Id, Name, Body from Attachment').first
+        File.open(attachment.Name, 'wb') { |f| f.write(attachment.Body) }
+
+## 1.0.6 (Feb 16, 2013)
+
+*   Added `url` method.
+
+    Example
+
+        # Url to a record id
+        client.url('0013000000rRz')
+        # => https://na1.salesforce.com/0013000000rRz
+
+        # Url to an object that responds to `to_sparam`
+        record = Struct.new(:to_sparam).new('0013000000rRz')
+        client.url('0013000000rRz')
+        # => https://na1.salesforce.com/0013000000rRz
+
+
+## 1.0.5 (Jan 11, 2013)
+
+*   Added `picklist_values` method.
+
+    Example
+
+        client.picklist_values('Account', 'Type')
+
+        client.picklist_values('Automobile__c', 'Model__c', :valid_for => 'Honda')
+
+*   Added CHANGELOG.md
+
+## 1.0.4 (Jan 8, 2013)
+
+*   `Sfdc::Client#inspect` now only prints out the options and not the
+    Faraday connection.
+
+*   The Faraday adapter is now configurabled:
+
+    Example:
+
+        Sfdc.configure do |config|
+          config.adapter = :excon
+        end
+
+*   The http connection read/open timeout is now configurabled.
+
+    Example:
+
+        Sfdc.configure do |config|
+          config.timeout = 300
+        end
+
+## 1.0.3 (Jan 7, 2013)
+
+*   Fixed typo in method call.
+
+## 1.0.2 (Jan 7, 2013)
+
+*   Minor cleanup.
+*   Moved decoding of signed requests into it's own class.
+
+## 1.0.1 (Dec 31, 2012)
+
+*   `username`, `password`, `security_token`, `client_id` and `client_secret`
+    options now obtain defaults from environment variables.
+*   Add `head` verb.
+
+## 1.0.0 (Dec 23, 2012)
+
+*   Default api version changed from 24.0 to 26.0.
+*   Fixed tests for streaming api to work with latest versions of faye.
+*   Added .find method to obtain all fields from an sobject.

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sfdc.gemspec
+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/sfdc/(.+)\.rb$})    { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch(%r{^lib/sfdc/(.+)\.rb$})    { |m| "spec/integration/#{m[1]}_spec.rb" }
+  watch(%r{^spec/support/(.+)\.rb$}) { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Eric J. Holmes
+
+With portions Copyright (c) 2013 Heroku (http://heroku.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,9 +1,19 @@
 # Sfdc
 
-Sfdc is a ruby gem for the [Salesforce REST api](http://www.salesforce.com/us/developer/docs/api_rest/index.htm).
+_A ruby gem for the [Salesforce REST api](http://www.salesforce.com/us/developer/docs/api_rest/index.htm)._
 
-Features include:
+## Features
 
+- A clean and modular architecture using [Faraday middleware](https://github.com/technoweenie/faraday) and [Hashie::Mash](https://github.com/intridea/hashie/tree/v1.2.0)'d responses.
+- Support for interacting with multiple users from different orgs.
+- Support for parent-to-child relationships.
+- Support for aggregate queries.
+- Support for the [Streaming API](#streaming)
+- Support for blob data types.
+- Support for GZIP compression.
+- Support for [custom Apex REST endpoints](#custom-apex-rest-endpoints).
+- Support for dependent picklists.
+- Support for decoding [force.com Canvas](http://www.salesforce.com/us/developer/docs/platform_connectpre/canvas_framework.pdf) signed requests. (NEW!)
 
 ## Installation
 
@@ -22,7 +32,7 @@ Or install it yourself as:
 ## Usage
 
 Sfdc is designed with flexibility and ease of use in mind. By default, all api calls will
-return [Hashie::Mash](https://github.com/intridea/hashie/) objects,
+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`.
 
 ### Initialization
@@ -36,22 +46,22 @@ 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.
 
-#### OAuth token authentication
+#### OAuth Token Authentication
 
 ```ruby
-client = Sfdc.new :oauth_token => 'oauth token',
-  :instance_url  => 'instance url'
+client = Sfdc.new :instance_url => 'xx.salesforce.com',
+                   :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:
 
 ```ruby
-client = Sfdc.new :oauth_token => 'oauth token',
-  :refresh_token => 'refresh token',
-  :instance_url  => 'instance url',
-  :client_id     => 'client_id',
-  :client_secret => 'client_secret'
+client = Sfdc.new :instance_url => 'xx.salesforce.com',
+                   :oauth_token => '...',
+                   :refresh_token => '...',
+                   :client_id => '...',
+                   :client_secret => '...'
 ```
 
 #### Username/Password authentication
@@ -59,11 +69,11 @@ client = Sfdc.new :oauth_token => 'oauth token',
 If you prefer to use a username and password to authenticate:
 
 ```ruby
-client = Sfdc.new :username => 'foo',
-  :password       => 'bar',
-  :security_token => 'security token'
-  :client_id      => 'client_id',
-  :client_secret  => 'client_secret'
+client = Sfdc.new :username => 'user@example.com',
+                   :password => '...',
+                   :security_token => '...',
+                   :client_id => '...',
+                   :client_secret => '...'
 ```
 
 You can also set the username, password, security token, client id and client
@@ -80,49 +90,39 @@ export SALESFORCE_CLIENT_SECRET="client secret"
 ```ruby
 client = Sfdc.new
 ```
+
 ### Proxy Support
 
 You can specify a http proxy using the :proxy_uri option, as follows:
 
 ```ruby
-client = Sfdc.new :username => 'foo',
-  :password       => 'bar',
-  :security_token => 'security token'
-  :client_id      => 'client_id',
-  :client_secret  => 'client_secret',
-  :proxy_uri      => 'http://proxy.example.com:123'
+client = Sfdc.new :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.
+
+This paramter also will accept `http://user@password:proxy.example.com:123` or using the environemnt variable `PROXY_URI`.
 
 #### Sandbox Orgs
 
 You can connect to sandbox orgs by specifying a host. The default host is
-'login.salesforce.com':
+`login.salesforce.com`:
 
 ```ruby
 client = Sfdc.new :host => 'test.salesforce.com'
 ```
+The host can also be set with the environment variable `SALESFORCE_HOST`.
 
-#### Global configuration
+#### Global Configuration
 
 You can set any of the options passed into Sfdc.new globally:
 
 ```ruby
 Sfdc.configure do |config|
-  config.client_id     = 'foo'
+  config.client_id = 'foo'
   config.client_secret = 'bar'
 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
-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.
-
-* * *
+---
 
 ### query
 
@@ -130,7 +130,7 @@ works similarly to ActiveRecord.
 accounts = client.query("select Id, Something__c from Account where Id = 'someid'")
 # => #<Sfdc::Collection >
 
-account = records.first
+account = accounts.first
 # => #<Sfdc::SObject >
 
 account.sobject_type
@@ -172,67 +172,63 @@ client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
 ### create
 
 ```ruby
-# Add a new account
-client.create('Account', Name: 'Foobar Inc.')
-# => '0016000000MRatd'
+client.create('Account', Name: 'Foobar Inc.') # => '0016000000MRatd'
 ```
 
 ### update
 
 ```ruby
-# Update the Account with Id '0016000000MRatd'
-client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
-# => true
+client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp') # => true
 ```
 
 ### upsert
 
 ```ruby
-# Update the record with external ID of 12
-client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
+client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar') # => true
 ```
 
 ### destroy
 
 ```ruby
-# Delete the Account with Id '0016000000MRatd'
-client.destroy('Account', '0016000000MRatd')
-# => true
+client.destroy('Account', '0016000000MRatd') # => true
 ```
 
+> 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.
+
 ### describe
 
 ```ruby
-# get the global describe for all sobjects
-client.describe
-# => { ... }
-
-# get the describe for the Account object
-client.describe('Account')
-# => { ... }
+client.describe # => { ... }
+client.describe('Account') # => { ... }
 ```
 
-### picklist\_values
+### describe_layouts
 
+```ruby
+client.describe_layout('Account') # => { ... }
+client.describe_layouts('Account', '012E0000000RHEp') # => { ... }
+```
+
+### picklist_values
 
 ```ruby
-client.picklist_values('Account', 'Type')
-# => [#<Sfdc::Mash label="Prospect" value="Prospect">]
+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.
+# 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">, ... ]
 ```
 
-* * *
+---
 
 ### authenticate!
 
 Performs an authentication and returns the response. In general, calling this
 directly shouldn't be required, since the client will handle authentication for
-you automatically. This should only be used if you want to force
+you automatically. This should only be used if you want to sfdc
 an authentication before using the streaming api, or you want to get some
 information about the user.
 
@@ -246,31 +242,29 @@ info.user_id
 # => '005E0000001eM4LIAU'
 ```
 
-* * *
-
 ### File Uploads
 
 Using the new [Blob Data](http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_insert_update_blob.htm) api feature (500mb limit):
 
 ```ruby
+image = Sfdc::UploadIO.new(File.expand_path('image.jpg', __FILE__), 'image/jpeg')
 client.create 'Document', FolderId: '00lE0000000FJ6H',
-  Description: 'Document test',
-  Name: 'My image',
-  Body: Sfdc::UploadIO.new(File.expand_path('image.jpg', __FILE__), 'image/jpeg'))
+                          Description: 'Document test',
+                          Name: 'My image',
+                          Body: image)
 ```
 
-Using base64 encoded data (37.5mb limit):
+Using base64-encoded data _(37.5mb limit)_:
 
 ```ruby
+data = Base64::encode64(File.read('image.jpg')
 client.create 'Document', FolderId: '00lE0000000FJ6H',
-  Description: 'Document test',
-  Name: 'My image',
-  Body: Base64::encode64(File.read('image.jpg'))
+                          Description: 'Document test',
+                          Name: 'My image',
+                          Body: data)
 ```
 
-_See also: http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_insert_update_blob.htm_
-
-* * *
+> See also: http://www.salesforce.com/us/developer/docs/api_rest/Content/dome_sobject_insert_update_blob.htm
 
 ### Downloading Attachments
 
@@ -281,8 +275,6 @@ attachment = client.query('select Id, Name, Body from Attachment').first
 File.open(attachment.Name, 'wb') { |f| f.write(attachment.Body) }
 ```
 
-* * *
-
 ### Custom Apex REST endpoints
 
 You can use Sfdc to interact with your custom REST endpoints, by using
@@ -304,7 +296,7 @@ global class RESTCaseController {
 }
 ```
 
-Then you could query the cases using Sfdc:
+...then you could query the cases using Sfdc:
 
 ```ruby
 client.get '/services/apexrest/FieldCase', :company => 'GenePoint'
@@ -315,7 +307,7 @@ client.get '/services/apexrest/FieldCase', :company => 'GenePoint'
 
 ### Streaming
 
-Sfdc supports the [Streaming API](http://wiki.developerforce.com/page/Getting_Started_with_the_Force.com_Streaming_API), and makes implementing
+Sfdc supports the [Streaming API](http://wiki.developerforce.com/page/Getting_Started_with_the_Sfdc.com_Streaming_API), and makes implementing
 pub/sub with Salesforce a trivial task:
 
 ```ruby
@@ -347,9 +339,6 @@ EM.run {
 }
 ```
 
-Boom, you're now receiving push notifications when Accounts are
-created/updated.
-
 _See also: http://www.salesforce.com/us/developer/docs/api_streaming/index.htm_
 
 * * *
@@ -377,11 +366,9 @@ client.without_caching do
 end
 ```
 
-* * *
-
-### Logging/Debugging/Instrumenting
+### Logging / Debugging / Instrumenting
 
-You can easily inspect what Sfdc is sending/receiving by setting
+You can inspect what Sfdc is sending/receiving by setting
 `Sfdc.log = true`.
 
 ```ruby
@@ -389,18 +376,20 @@ Sfdc.log = true
 client = Sfdc.new.query('select Id, Name from Account')
 ```
 
-Another awesome feature about Sfdc is that, because it is based on
-Faraday, you can insert your own middleware. For example, if you were using
-Sfdc in a rails app, you can setup custom reporting to
-[Librato](https://github.com/librato/librato-rails) using ActiveSupport::Notifications:
+Another awesome feature about sfdc is that, because it is based on Faraday, you can insert your own middleware. 
+
+For example, if you were using Sfdc in a Rails app, you can setup custom reporting to [Librato](https://github.com/librato/librato-rails) using ActiveSupport::Notifications:
 
 ```ruby
 client = Sfdc.new do |builder|
   builder.insert_after Sfdc::Middleware::InstanceURL,
-    FaradayMiddleware::Instrumentation, name: 'request.salesforce'
+                       FaradayMiddleware::Instrumentation, name: 'request.salesforce'
 end
+```
 
-# config/initializers/notifications.rb
+#### config/initializers/notifications.rb
+
+```ruby
 ActiveSupport::Notifications.subscribe('request.salesforce') do |*args|
   event = ActiveSupport::Notifications::Event.new(*args)
   Librato.increment 'api.salesforce.request.total'
@@ -408,7 +397,7 @@ ActiveSupport::Notifications.subscribe('request.salesforce') do |*args|
 end
 ```
 
-## Force.com Canvas
+## Sfdc.com Canvas
 
 You can use Sfdc to decode signed requests from Salesforce. See [the example app](https://gist.github.com/4052312).
 
@@ -421,11 +410,12 @@ call `Sfdc.tooling` instead of `Sfdc.new`:
 client = Sfdc.tooling(...)
 ```
 
+---
+
+## Contact
+
+- Mattt Thompson <mattt@heroku.com>
 
-## Contributing
+## License
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Sfdc is available under the MIT license. See the LICENSE file for more info.