restforce 0.0.2 → 0.0.3

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+test.rb
 .bundle
 .config
 .yardoc

data/README.md

@@ -89,8 +89,8 @@ You can set any of the options passed into Restforce::Client.new globally:
 
 ```ruby
 Restforce.configure do |config|
-    config.client_id     = ENV['SALESFORCE_CLIENT_ID']
-    config.client_secret = ENV['SALESFORCE_CLIENT_SECRET']
+  config.client_id     = ENV['SALESFORCE_CLIENT_ID']
+  config.client_secret = ENV['SALESFORCE_CLIENT_SECRET']
 end
 ```
 
@@ -142,6 +142,14 @@ 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')
+```
+
 ### Destroy
 
 ```ruby
@@ -152,6 +160,8 @@ client.destroy('Account', '0016000000MRatd')
 
 ### 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
 client.create 'Document', FolderId: '00lE0000000FJ6H',
   Description: 'Document test',
@@ -159,6 +169,38 @@ client.create 'Document', FolderId: '00lE0000000FJ6H',
   Body: Restforce::UploadIO.new(File.expand_path('image.jpg', __FILE__), 'image/jpeg'))
 ```
 
+Using base64 encoded data (37.5mb limit):
+
+```ruby
+client.create 'Document', FolderId: '00lE0000000FJ6H',
+  Description: 'Document test',
+  Name: 'My image',
+  Body: Base64::encode64(File.read('image.jpg'))
+```
+
+### Streaming
+
+Restforce supports the [Streaming API](http://wiki.developerforce.com/page/Getting_Started_with_the_Force.com_Streaming_API), and makes implementing
+pub/sub with Salesforce a trivial task:
+
+```ruby
+# Initialize a client with your username/password/oauth token/etc
+client = Restforce::Client.new
+
+# Force an authentication request
+client.authenticate!
+
+EM.run {
+  # Assuming you've setup a PushTopic called 'AllAccounts' (See the link above.)
+  client.subscribe 'AllAccounts' do |message|
+    puts message.inspect
+  end
+}
+```
+
+Boom, you're now receiving push notifications when Accounts are
+created/updated.
+
 ## Contributing
 
 1. Fork it

data/lib/restforce.rb

@@ -1,6 +1,7 @@
 require 'faraday'
 require 'faraday_middleware'
 require 'json'
+require 'faye'
 
 require 'restforce/version'
 require 'restforce/config'

data/lib/restforce/client.rb

@@ -110,6 +110,8 @@ module Restforce
     
     # Public: Executs a SOQL query and returns the result.
     #
+    # soql - A SOQL expression.
+    #
     # Examples
     #
     #   # Find the names of all Accounts
@@ -118,13 +120,15 @@ module Restforce
     #
     # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
     # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
-    def query(query)
-      response = api_get 'query', q: query
+    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'
@@ -137,8 +141,8 @@ module Restforce
     #
     # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
     # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
-    def search(term)
-      response = api_get 'search', q: term
+    def search(sosl)
+      response = api_get 'search', q: sosl
       response.body
     end
     
@@ -150,8 +154,19 @@ module Restforce
     #   client.create('Account', Name: 'Foobar Inc.')
     #   # => '0016000000MRatd'
     #
-    # Returns the String Id of the newly created sobject.
+    # Returns the String Id of the newly created sobject. Returns false if
+    # something bad happens
     def create(sobject, attrs)
+      create!(sobject, attrs)
+    rescue *exceptions
+      false
+    end
+
+    # See .create
+    #
+    # Returns the String Id of the newly created sobject. Raises an error if
+    # something bad happens.
+    def create!(sobject, attrs)
       response = api_post "sobjects/#{sobject}", attrs
       response.body['id']
     end
@@ -166,7 +181,7 @@ module Restforce
     # Returns true if the sobject was successfully updated, false otherwise.
     def update(sobject, attrs)
       update!(sobject, attrs)
-    rescue Faraday::Error::ResourceNotFound
+    rescue *exceptions
       false
     end
 
@@ -180,6 +195,37 @@ module Restforce
       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(sobject, field, attrs)
+      upsert!(sobject, field, attrs)
+    rescue *exceptions
+      false
+    end
+
+    # See .upsert
+    #
+    # Returns true if the record was found and updated.
+    # Returns the Id of the newly created record if the record was created.
+    # Raises an error if something bad happens.
+    def upsert!(sobject, field, attrs)
+      external_id = attrs.has_key?(field.to_sym) ? attrs.delete(field.to_sym) : attrs.delete(field.to_s)
+      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.
     #
     # Examples
@@ -190,7 +236,7 @@ module Restforce
     # Returns true if the sobject was successfully deleted, false otherwise.
     def destroy(sobject, id)
       destroy!(sobject, id)
-    rescue Faraday::Error::ResourceNotFound
+    rescue *exceptions
       false
     end
 
@@ -203,6 +249,24 @@ module Restforce
       true
     end
 
+    # Public: Subscribe to a PushTopic
+    #
+    # channel - The name of the PushTopic channel to subscribe to.
+    # block   - A block to run when a new message is received.
+    #
+    # Returns a Faye::Subscription
+    def subscribe(channel, &block)
+      faye.subscribe "/topic/#{channel}", &block
+    end
+
+    # Public: Force an authentication
+    def authenticate!
+      connection.headers['X-ForceAuthenticate'] = true
+      get nil
+    ensure
+      connection.headers.delete('X-ForceAuthenticate')
+    end
+
     # Public: Helper methods for performing arbitrary actions against the API using
     # various HTTP verbs.
     #
@@ -275,7 +339,7 @@ module Restforce
       if username_password?
         Restforce::Middleware::Authentication::Password
       elsif oauth_refresh?
-        Restforce::Middleware::Authentication::OAuth
+        Restforce::Middleware::Authentication::Token
       end
     end
 
@@ -292,8 +356,7 @@ module Restforce
     # Internal: Returns true if oauth token refresh flow should be used for
     # authentication.
     def oauth_refresh?
-      @options[:oauth_token] &&
-        @options[:refresh_token] &&
+      @options[:refresh_token] &&
         @options[:client_id] &&
         @options[:client_secret]
     end
@@ -303,5 +366,23 @@ module Restforce
     def mashify?
       connection.builder.handlers.find { |handler| handler == Restforce::Middleware::Mashify }
     end
+
+    # Internal: Errors that should be rescued from in non-bang methods
+    def exceptions
+      [Faraday::Error::ClientError]
+    end
+
+    # Internal: Faye client to use for subscribing to PushTopics
+    def faye
+      @faye ||= Faye::Client.new("#{@options[:instance_url]}/cometd/#{@options[:api_version]}").tap do |client|
+        client.set_header 'Authorization', "OAuth #{@options[:oauth_token]}"
+        client.bind 'transport:down' do
+          Restforce.log "[COMETD DOWN]"
+        end
+        client.bind 'transport:up' do
+          Restforce.log "[COMETD UP]"
+        end
+      end
+    end
   end
 end

data/lib/restforce/collection.rb

@@ -6,12 +6,7 @@ module Restforce
       @client        = client
       @total_size    = hash['totalSize']
       @next_page_url = hash['nextRecordsUrl']
-      super(self.build(hash['records']))
-    end
-
-    # Converts an array of Hash's into an array of Restforce::SObject.
-    def build(array)
-      array.map { |record| Restforce::SObject.new(record, @client) }
+      super(Restforce::Mash.build(hash['records'], @client))
     end
 
     def next_page

data/lib/restforce/middleware.rb

@@ -24,7 +24,7 @@ end
 require 'restforce/middleware/raise_error'
 require 'restforce/middleware/authentication'
 require 'restforce/middleware/authentication/password'
-require 'restforce/middleware/authentication/oauth'
+require 'restforce/middleware/authentication/token'
 require 'restforce/middleware/authorization'
 require 'restforce/middleware/instance_url'
 require 'restforce/middleware/mashify'

data/lib/restforce/middleware/authentication.rb

@@ -8,6 +8,7 @@ module Restforce
 
     def call(env)
       begin
+        return authenticate! if force_authenticate?(env)
         @app.call(env)
       rescue Restforce::UnauthorizedError
         authenticate!
@@ -26,6 +27,10 @@ module Restforce
         builder.adapter Faraday.default_adapter
       end
     end
+
+    def force_authenticate?(env)
+      env[:request_headers] && env[:request_headers]['X-ForceAuthenticate']
+    end
   
   end
 

data/lib/restforce/middleware/authentication/{oauth.rb → token.rb}

@@ -1,7 +1,7 @@
 module Restforce
 
   # Authentication middleware used if oauth_token and refresh_token are set
-  class Middleware::Authentication::OAuth < Restforce::Middleware::Authentication
+  class Middleware::Authentication::Token < Restforce::Middleware::Authentication
 
     def authenticate!
       response = connection.post '/services/oauth2/token' do |req|

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/restforce.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'faraday_middleware', '~> 0.8.8'
   gem.add_dependency 'json', '~> 1.7.5'
   gem.add_dependency 'hashie', '~> 1.2.0'
+  gem.add_dependency 'faye'
 
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'webmock'

data/spec/fixtures/sobject/upsert_created_success_response.json

@@ -1,2 +1 @@
-{"id":"foo" +
-"","errors":[],"success":true}
+{"id":"foo","errors":[],"success":true}

data/spec/lib/client_spec.rb

@@ -46,10 +46,10 @@ shared_examples_for 'methods' do
       it { should eq Restforce::Middleware::Authentication::Password }
     end
 
-    context 'with oauth token, refresh token, client id and client secret provided' do
+    context 'with refresh token, client id and client secret provided' do
       let(:client_options) { oauth_options }
 
-      it { should eq Restforce::Middleware::Authentication::OAuth }
+      it { should eq Restforce::Middleware::Authentication::Token }
     end
   end
   
@@ -213,6 +213,48 @@ shared_examples_for 'methods' do
     end
   end
 
+  describe '.upsert!' do
+    context 'when updated' do
+      before do
+        @request = stub_api_request 'sobjects/Account/External__c/foobar', method: :patch, body: "{\"Name\":\"Foobar\"}"
+      end
+
+      after do
+        @request.should have_been_requested
+      end
+
+      context 'with symbol external Id key' do
+        subject { client.upsert!('Account', 'External__c', External__c: 'foobar', Name: 'Foobar') }
+        it { should be_true }
+      end
+
+      context 'with string external Id key' do
+        subject { client.upsert!('Account', 'External__c', 'External__c' => 'foobar', 'Name' => 'Foobar') }
+        it { should be_true }
+      end
+    end
+
+    context 'when created' do
+      before do
+        @request = stub_api_request 'sobjects/Account/External__c/foobar', method: :patch, body: "{\"Name\":\"Foobar\"}", with: 'sobject/upsert_created_success_response'
+      end
+
+      after do
+        @request.should have_been_requested
+      end
+
+      context 'with symbol external Id key' do
+        subject { client.upsert!('Account', 'External__c', External__c: 'foobar', Name: 'Foobar') }
+        it { should eq 'foo' }
+      end
+
+      context 'with string external Id key' do
+        subject { client.upsert!('Account', 'External__c', 'External__c' => 'foobar', 'Name' => 'Foobar') }
+        it { should eq 'foo' }
+      end
+    end
+  end
+
   describe '.destroy!' do
     subject { client.destroy!('Account', '001D000000INjVe') }
 
@@ -268,6 +310,22 @@ shared_examples_for 'methods' do
       it { should be_true }
     end
   end
+
+  describe '.authenticate!' do
+    before do
+      @request = stub_request(:post, "https://login.salesforce.com/services/oauth2/token").
+        with(:body => "grant_type=password&client_id=client_id&client_secret=" \
+        "client_secret&username=foo&password=barsecurity_token").
+        to_return(:status => 200, :body => fixture(:auth_success_response))
+    end
+
+    after do
+      @request.should have_been_requested
+    end
+
+    subject { client.authenticate! }
+    specify { expect { subject }.to_not raise_error }
+  end
 end
 
 describe 'with mashify middleware' do

data/spec/lib/collection_spec.rb

@@ -39,7 +39,7 @@ describe Restforce::Collection do
 
       describe '.next_page' do
         before do
-          client.should_receive(:get).and_return(Faraday::Response.new(body: Restforce::Collection.new({'records' => {}}, client)))
+          client.should_receive(:get).and_return(Faraday::Response.new(body: Restforce::Collection.new({'records' => []}, client)))
         end
 
         subject { records.next_page }

data/spec/lib/mash_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe Restforce::Mash do
+  describe '#build' do
+    subject { described_class.build(input, nil) }
+
+    context 'when array' do
+      let(:input) { [{ foo: 'hello' }, { bar: 'world' }] }
+      it 'mashifys each child object' do
+        subject.each { |obj| obj.should be_a Restforce::Mash }
+      end
+    end
+  end
+
+  describe '#klass' do
+    subject { described_class.klass(input) }
+
+    context 'when the hash has a "records" key' do
+      let(:input) { { 'records' => nil } }
+      it { should eq Restforce::Collection }
+    end
+
+    context 'when the hash has an "attributes" key' do
+      let(:input) { { 'attributes' => nil } }
+      it { should eq Restforce::SObject }
+    end
+
+    context 'else' do
+      let(:input) { {} }
+      it { should eq Restforce::Mash }
+    end
+  end
+end

data/spec/lib/middleware/authentication/{oauth_spec.rb → token_spec.rb}

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe Restforce::Middleware::Authentication::OAuth do
+describe Restforce::Middleware::Authentication::Token do
   let(:app)        { double('app')            }
   let(:env)        { { }  }
   let(:middleware) { described_class.new app, nil, options }

data/spec/lib/middleware/authentication_spec.rb

@@ -64,4 +64,21 @@ describe Restforce::Middleware::Authentication do
       end
     end
   end
+
+  describe '.force_authenticate?' do
+    subject { middleware.force_authenticate?(env) }
+
+    context 'without X-ForceAuthenticate header set' do
+      it { should be_false }
+    end
+
+    context 'with X-ForceAuthenticate header set' do
+      before do
+        env[:request_headers] = {}
+        env[:request_headers]['X-ForceAuthenticate'] = true
+      end
+
+      it { should be_true }
+    end
+  end
 end

data/spec/support/basic_client.rb

@@ -22,7 +22,7 @@ shared_context 'basic client' do
   end
 
   let(:oauth_options) do
-    base_options.merge(:username => nil, :password => nil, :security_token => nil)
+    base_options.merge(:username => nil, :password => nil, :security_token => nil, :oauth_token => nil)
   end
 
   let(:password_options) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-06 00:00:00.000000000 Z
+date: 2012-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70194283587720 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70194283587720
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &70194283586980 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +37,15 @@ dependencies:
         version: 0.8.4
   type: :runtime
   prerelease: false
-  version_requirements: *70194283586980
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.4
 - !ruby/object:Gem::Dependency
   name: faraday_middleware
-  requirement: &70194283586260 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +53,15 @@ dependencies:
         version: 0.8.8
   type: :runtime
   prerelease: false
-  version_requirements: *70194283586260
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.8
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70194283585800 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +69,15 @@ dependencies:
         version: 1.7.5
   type: :runtime
   prerelease: false
-  version_requirements: *70194283585800
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.5
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &70194283601640 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +85,31 @@ dependencies:
         version: 1.2.0
   type: :runtime
   prerelease: false
-  version_requirements: *70194283601640
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: faye
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70194283601040 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +117,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70194283601040
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &70194283600360 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +133,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70194283600360
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70194283599880 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +149,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70194283599880
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A lightweight ruby client for the Salesforce REST api.
 email:
 - eric@ejholmes.net
@@ -120,8 +176,8 @@ files:
 - lib/restforce/mash.rb
 - lib/restforce/middleware.rb
 - lib/restforce/middleware/authentication.rb
-- lib/restforce/middleware/authentication/oauth.rb
 - lib/restforce/middleware/authentication/password.rb
+- lib/restforce/middleware/authentication/token.rb
 - lib/restforce/middleware/authorization.rb
 - lib/restforce/middleware/instance_url.rb
 - lib/restforce/middleware/mashify.rb
@@ -165,8 +221,9 @@ files:
 - spec/lib/client_spec.rb
 - spec/lib/collection_spec.rb
 - spec/lib/config_spec.rb
-- spec/lib/middleware/authentication/oauth_spec.rb
+- spec/lib/mash_spec.rb
 - spec/lib/middleware/authentication/password_spec.rb
+- spec/lib/middleware/authentication/token_spec.rb
 - spec/lib/middleware/authentication_spec.rb
 - spec/lib/middleware/authorization_spec.rb
 - spec/lib/middleware/instance_url_spec.rb
@@ -197,7 +254,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: A lightweight ruby client for the Salesforce REST api.
@@ -236,8 +293,9 @@ test_files:
 - spec/lib/client_spec.rb
 - spec/lib/collection_spec.rb
 - spec/lib/config_spec.rb
-- spec/lib/middleware/authentication/oauth_spec.rb
+- spec/lib/mash_spec.rb
 - spec/lib/middleware/authentication/password_spec.rb
+- spec/lib/middleware/authentication/token_spec.rb
 - spec/lib/middleware/authentication_spec.rb
 - spec/lib/middleware/authorization_spec.rb
 - spec/lib/middleware/instance_url_spec.rb