restforce 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+script: bundle exec rake

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in restforce.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Eric J. Holmes
+
+MIT License
+
+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

@@ -0,0 +1,161 @@
+# Restforce [![travis-ci](https://secure.travis-ci.org/ejholmes/restforce.png)](https://secure.travis-ci.org/ejholmes/restforce)
+
+Restforce is a ruby gem for the [Salesforce REST api](http://www.salesforce.com/us/developer/docs/api_rest/index.htm).
+It's meant to be a lighter weight alternative to the [databasedotcom gem](https://github.com/heroku/databasedotcom).
+
+It attempts to solve a couple of key issues that the databasedotcom gem has been unable to solve:
+
+* Support for interacting with multiple users from different orgs.
+* Support for parent-to-child relationships.
+* Support for aggregate queries.
+* Remove the need to materialize constants.
+* Support for the Streaming API
+* A clean and modular architecture using [Faraday middleware](https://github.com/technoweenie/faraday)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'restforce
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install restforce
+
+## Usage
+
+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`.
+
+### Initialization
+
+Which authentication method you use really depends on your use case. If you're
+building an application where many users from different orgs are authenticated
+through oauth and you need to interact with data in their org on their behalf,
+you should use the OAuth token authentication method.
+
+If you're using the gem to interact with a single org (maybe you're building some
+salesforce integration internally?) then you should use the username/password
+authentication method.
+
+If you have an access token and an instance url obtained through oauth:
+
+#### OAuth token authentication
+
+```ruby
+client = Restforce::Client.new :oauth_token => 'oauth token',
+  :instance_url  => 'instance url'
+```
+
+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 = Restforce::Client.new :oauth_token => 'oauth token',
+  :refresh_token => 'refresh token',
+  :instance_url  => 'instance url',
+  :client_id     => 'client_id',
+  :client_secret => 'client_secret'
+```
+
+#### Username/Password authentication
+
+If you prefer to use a username and password to authenticate:
+
+```ruby
+client = Restforce::Client.new :username => 'foo',
+  :password       => 'bar',
+  :security_token => 'security token'
+  :client_id      => 'client_id',
+  :client_secret  => 'client_secret'
+```
+
+#### Sandbox Orgs
+
+You can connect to sandbox orgs by specifying a host. The default host is
+'login.salesforce.com':
+
+```ruby
+client = Restforce::Client.new :host => 'test.salesforce.com'
+```
+
+#### Global configuration
+
+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']
+end
+```
+
+### Query
+
+```ruby
+accounts = client.query("select Id, Something__c from Account where Id = 'someid'")
+# => #<Restforce::Collection >
+
+account = records.first
+# => #<Restforce::SObject >
+
+account.Id
+# => "someid"
+
+account.Name = 'Foobar'
+account.save
+# => true
+
+account.destroy
+# => true
+```
+
+### Search
+
+```ruby
+# Find all occurrences of 'bar'
+client.search('FIND {bar}')
+# => #<Restforce::Collection >
+
+# Find accounts match the term 'genepoint' and return the Name field
+client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
+# => ['GenePoint']
+```
+
+### Create
+
+```ruby
+# Add a new account
+client.create('Account', Name: 'Foobar Inc.')
+# => '0016000000MRatd'
+```
+
+### Update
+
+```ruby
+# Update the Account with Id '0016000000MRatd'
+client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+# => true
+```
+
+### Destroy
+
+```ruby
+# Delete the Account with Id '0016000000MRatd'
+client.destroy('Account', '0016000000MRatd')
+# => true
+```
+
+
+## Contributing
+
+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

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+task :default => [:spec]
+
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end

data/lib/restforce.rb

@@ -0,0 +1,18 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'json'
+
+require 'restforce/version'
+require 'restforce/config'
+require 'restforce/mash'
+require 'restforce/collection'
+require 'restforce/sobject'
+require 'restforce/client'
+
+require 'restforce/middleware'
+
+module Restforce
+  class AuthenticationError < StandardError; end
+  class UnauthorizedError < StandardError; end
+  class InstanceURLError < StandardError; end
+end

data/lib/restforce/client.rb

@@ -0,0 +1,287 @@
+module Restforce
+  class Client
+    # Public: Creates a new client instance
+    #
+    # options - 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')
+    #
+    # 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'
+    #   # => #<Restforce::Client:0x007f934aa2dc28 @options={ ... }>
+    #
+    #   # 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'
+    #   # => #<Restforce::Client:0x007f934aaaa0e8 @options={ ... }>
+    #
+    #   # Initialize a new client with using any authentication middleware:
+    #   Restforce::Client.new :oauth_token => 'access token',
+    #     :instance_url => 'https://na1.salesforce.com'
+    #   # => #<Restforce::Client:0x007f934aab9980 @options={ ... }>
+    def initialize(options = {})
+      raise 'Please specify a hash of options' unless options.is_a?(Hash)
+      @options = {}.tap do |options|
+        [:username, :password, :security_token, :client_id, :client_secret, :host,
+         :api_version, :oauth_token, :refresh_token, :instance_url].each do |option|
+          options[option] = Restforce.configuration.send option
+        end
+      end
+      @options.merge!(options)
+    end
+
+    # Public: Get the global describe for all sobjects.
+    #
+    # Returns the Hash representation of the describe call.
+    def describe_sobjects
+      response = api_get 'sobjects'
+      response.body['sobjects']
+    end
+
+    # 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_sobjects.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 describe for the Account object
+    #   client.describe('Account')
+    #   # => { ... }
+    #
+    # Returns the Hash representation of the describe call.
+    def describe(sobject)
+      response = api_get "sobject/#{sobject.to_s}/describe"
+      response.body
+    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.
+    #
+    # Examples
+    #
+    #   # Find the names of all Accounts
+    #   client.query('select Name from Account').map(&:Name)
+    #   # => ['Foo Bar Inc.', 'Whizbang Corp']
+    #
+    # 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
+      mashify? ? response.body : response.body['records']
+    end
+    
+    # Public: Perform a SOSL search
+    #
+    # Examples
+    #
+    #   # Find all occurrences of 'bar'
+    #   client.search('FIND {bar}')
+    #   # => #<Restforce::Collection >
+    #
+    #   # Find accounts match the term 'genepoint' and return the Name field
+    #   client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
+    #   # => ['GenePoint']
+    #
+    # 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
+      response.body
+    end
+    
+    # Public: Insert a new record.
+    #
+    # Examples
+    #
+    #   # Add a new account
+    #   client.create('Account', Name: 'Foobar Inc.')
+    #   # => '0016000000MRatd'
+    #
+    # Returns the String Id of the newly created sobject.
+    def create(sobject, attrs)
+      response = api_post "sobjects/#{sobject}", attrs
+      response.body['id']
+    end
+
+    # Public: Update a record.
+    #
+    # Examples
+    #
+    #   # Update the Account with Id '0016000000MRatd'
+    #   client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+    #
+    # Returns true if the sobject was successfully update, false otherwise.
+    def update(sobject, attrs)
+      id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('Id')
+      response = api_patch "sobjects/#{sobject}/#{id}", attrs
+      true
+    end
+
+    # Public: Delete a record.
+    #
+    # Examples
+    #
+    #   # Delete the Account with Id '0016000000MRatd'
+    #   client.delete('Account', '0016000000MRatd')
+    #
+    # Returns true if the sobject was successfully deleted, false otherwise.
+    def destroy(sobject, id)
+      response = api_delete "sobjects/#{sobject}/#{id}"
+      true
+    end
+
+    # 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.
+    [:get, :post, :put, :delete, :patch].each do |method|
+      define_method method do |*args|
+        begin
+          connection.send(method, *args)
+        rescue Restforce::InstanceURLError
+          connection.url_prefix = @options[:instance_url]
+          connection.send(method, *args)
+        end
+      end
+
+      define_method :"api_#{method}" do |*args|
+        args[0] = api_path(args[0])
+        send(method, *args)
+      end
+    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: Internal faraday connection where all requests go through
+    def connection
+      @connection ||= Faraday.new do |builder|
+        builder.use Restforce::Middleware::Mashify, self, @options
+        builder.request :json
+        builder.use authentication_middleware, self, @options if authentication_middleware
+        builder.use Restforce::Middleware::Authorization, self, @options
+        builder.use Restforce::Middleware::InstanceURL, self, @options
+        builder.use Restforce::Middleware::RaiseError
+        builder.response :logger, Restforce.configuration.logger if Restforce.log?
+        builder.response :json
+        builder.adapter Faraday.default_adapter
+      end
+      @connection.headers['Content-Type'] = 'application/json'
+      @connection
+    end
+
+    # Internal: Determines what middleware will be used based on the options provided
+    def authentication_middleware
+      if username_password?
+        Restforce::Middleware::Authentication::Password
+      elsif oauth_refresh?
+        Restforce::Middleware::Authentication::OAuth
+      end
+    end
+
+    # Internal: Returns true if username/password (autonomous) flow should be used for
+    # authentication.
+    def username_password?
+      @options[:username] &&
+        @options[:password] &&
+        @options[:security_token] &&
+        @options[:client_id] &&
+        @options[:client_secret]
+    end
+
+    # Internal: Returns true if oauth token refresh flow should be used for
+    # authentication.
+    def oauth_refresh?
+      @options[:oauth_token] &&
+        @options[:refresh_token] &&
+        @options[:client_id] &&
+        @options[:client_secret]
+    end
+
+    # Internal: Returns true if the middlware stack includes the
+    # Restforce::Middleware::Mashify middleware.
+    def mashify?
+      connection.builder.handlers.find { |handler| handler == Restforce::Middleware::Mashify }
+    end
+  end
+end