sfdc 0.0.1 → 1.0.0

data/lib/sfdc/chatter/record.rb

@@ -0,0 +1,122 @@
+require 'json'
+
+module Sfdc
+  module Chatter
+    # Superclasses all Chatter resources except feeds. Some methods may not be supported by the Force.com API for certain subclasses.
+    class Record
+      attr_reader :raw_hash, :name, :id, :url, :type, :client
+
+      # Create a new record from the returned JSON response of an API request. Sets the client, name, id, url, and type attributes. Saves the raw response as +raw_hash+.
+      def initialize(client, response)
+        @client = client
+        @raw_hash = response.is_a?(Hash) ? response : JSON.parse(response)
+        @name = @raw_hash["name"]
+        @id = @raw_hash["id"]
+        @url = @raw_hash["url"]
+        @type = @raw_hash["type"]
+      end
+
+      # Find a single Record or a Collection of records by id. _resource_id_ can be a single id or a list of ids.
+      def self.find(client, resource_id, parameters={})
+        if resource_id.is_a?(Array)
+          resource_ids = resource_id.join(',')
+          url = "/services/data/v#{client.version}/chatter/#{self.resource_name}/batch/#{resource_ids}"
+          response = JSON.parse(client.http_get(url, parameters).body)
+          good_results = response["results"].select { |r| r["statusCode"] == 200 }
+          collection = Sfdc::Collection.new(client, good_results.length)
+          good_results.each do |result|
+            collection << self.new(client, result["result"])
+          end
+          collection
+        else
+          path_components = ["/services/data/v#{client.version}/chatter"]
+          if parameters.has_key?(:user_id)
+            path_components << "users/#{parameters[:user_id]}"
+            parameters.delete(:user_id)
+          end
+          path_components << "#{self.resource_name}/#{resource_id}"
+          url = path_components.join('/')
+          response = JSON.parse(client.http_get(url, parameters).body)
+          self.new(client, response)
+        end
+      end
+
+      # Return a Collection of records that match the _query_.
+      def self.search(client, query, parameters={})
+        self.all(client, parameters.merge(self.search_parameter_name => query))
+      end
+
+      # Return a Collection of all records.
+      def self.all(client, parameters={})
+        path_components = ["/services/data/v#{client.version}/chatter"]
+        if parameters.has_key?(:user_id)
+          path_components << "users/#{parameters[:user_id]}"
+          parameters.delete(:user_id)
+        end
+        path_components << self.resource_name
+        url = path_components.join('/')
+        result = client.http_get(url, parameters)
+        response = JSON.parse(result.body)
+        collection = Sfdc::Collection.new(client, self.total_size_of_collection(response), response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        self.collection_from_response(response).each do |resource|
+          collection << self.new(client, resource)
+        end
+        collection
+      end
+
+      # Delete the Record identified by _resource_id_.
+      def self.delete(client, resource_id, parameters={})
+        path_components = ["/services/data/v#{client.version}/chatter"]
+        if parameters.has_key?(:user_id)
+          path_components << "users/#{parameters[:user_id]}"
+          parameters.delete(:user_id)
+        end
+        path_components << self.resource_name
+        path_components << resource_id
+        path = path_components.join('/')
+        client.http_delete(path, parameters)
+      end
+
+      # A Hash representation of the User that created this Record.
+      def user
+        self.raw_hash["user"]
+      end
+
+      # A Hash representation of the entity that is the parent of this Record.
+      def parent
+        self.raw_hash["parent"]
+      end
+
+      # Delete this record.
+      def delete(parameters={})
+        self.class.delete(self.client, self.id, parameters)
+      end
+
+      # Reload this record.
+      def reload
+        self.class.find(self.client, self.id)
+      end
+
+      # The REST resource name of this Record.
+      #
+      #    GroupMembership.resource_name  #=>  group-memberships
+      def self.resource_name
+        (self.name.split('::').last).resourcerize + "s"
+      end
+
+      protected
+
+      def self.total_size_of_collection(response)
+        response["total"] || response["totalMemberCount"]
+      end
+
+      def self.collection_from_response(response)
+        response[self.resource_name]
+      end
+
+      def self.search_parameter_name
+        :q
+      end
+    end
+  end
+end

data/lib/sfdc/chatter/subscription.rb

@@ -0,0 +1,9 @@
+require 'Sfdc/chatter/record'
+
+module Sfdc
+  module Chatter
+    # A representation of a user "following" some other entity.
+    class Subscription < Record
+    end
+  end
+end

data/lib/sfdc/chatter/user.rb

@@ -0,0 +1,153 @@
+require 'Sfdc/chatter/record'
+require 'Sfdc/chatter/photo_methods'
+
+module Sfdc
+  module Chatter
+    # Defines a User in your org.
+    class User < Record
+      include PhotoMethods
+
+      # Returns a Collection of Subscription objects that represents all followers of the User identified by _subject_id_.
+      def self.followers(client, subject_id="me")
+        url = "/services/data/v#{client.version}/chatter/users/#{subject_id}/followers"
+        result = client.http_get(url)
+        response = JSON.parse(result.body)
+        collection = Sfdc::Collection.new(client, response["total"], response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        response["followers"].each do |subscription|
+          collection << Subscription.new(client, subscription)
+        end
+        collection
+      end
+
+      # Returns a Collection of Subscription objects that represent all entities that the User identified by _subject_id_ is following.
+      def self.following(client, subject_id="me")
+        url = "/services/data/v#{client.version}/chatter/users/#{subject_id}/following"
+        result = client.http_get(url)
+        response = JSON.parse(result.body)
+        collection = Sfdc::Collection.new(client, response["total"], response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        response["following"].each do |subscription|
+          collection << Subscription.new(client, subscription)
+        end
+        collection
+      end
+
+      # Returns a Collection of Group objects that represent all the groups that the User identified by _subject_id_ is a part of.
+      def self.groups(client, subject_id="me")
+        url = "/services/data/v#{client.version}/chatter/users/#{subject_id}/groups"
+        result = client.http_get(url)
+        response = JSON.parse(result.body)
+        collection = Sfdc::Collection.new(client, response["total"], response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        response["groups"].each do |group|
+          collection << Group.new(client, group)
+        end
+        collection
+      end
+
+      # Returns the current status of the User identified by _subject_id_.
+      def self.status(client, subject_id="me")
+        url = "/services/data/v#{client.version}/chatter/users/#{subject_id}/status"
+        result = client.http_get(url)
+        JSON.parse(result.body)
+      end
+
+      # Posts a status update as the User identified by _subject_id_ with content _text_.
+      def self.post_status(client, subject_id, text)
+        url = "/services/data/v#{client.version}/chatter/users/#{subject_id}/status"
+        result = client.http_post(url, nil, :text => text)
+        JSON.parse(result.body)
+      end
+
+      # Deletes the status of User identified by _subject_id_.
+      def self.delete_status(client, subject_id="me")
+        client.http_delete "/services/data/v#{client.version}/chatter/users/#{subject_id}/status"
+      end
+
+      # Creates and returns a new Subscription object that represents the User identified by _subject_id_ following the resource identified by _resource_id_.
+      def self.follow(client, subject_id, resource_id)
+        response = client.http_post("/services/data/v#{client.version}/chatter/users/#{subject_id}/following", nil, :subjectId => resource_id)
+        Subscription.new(client, response.body)
+      end
+
+      # Returns a Collection of conversations that belong to the User identified by _subject_id_.
+      def self.conversations(client, subject_id)
+        Conversation.all(client, :user_id => subject_id)
+      end
+
+      # Returns a Collection of private messages that belong to the User identified by _subject_id_.
+      def self.messages(client, subject_id)
+        Message.all(client, :user_id => subject_id)
+      end
+
+      # Get a Collection of Subscription objects for this User. Always makes a call to the server.
+      def followers!
+        self.class.followers(self.client, self.id)
+      end
+
+      # Get a Collection of Subscription objects for this User. Returns cached data if it has been called before.
+      def followers
+        @followers ||= followers!
+      end
+
+      # Get a Collection of Subscription objects that represents all resources that this User is following. Always makes a call to the server.
+      def following!
+        self.class.following(self.client, self.id)
+      end
+
+      # Get a Collection of Subscription objects that represents all resources that this User is following. Returns cached data if it has been called before.
+      def following
+        @following ||= following!
+      end
+
+      # Returns this current status of this User.
+      def status
+        self.raw_hash["currentStatus"]
+      end
+
+      # Posts a new status with content _text_ for this User.
+      def post_status(text)
+        self.class.post_status(self.client, self.id, text)
+      end
+
+      # Deletes the current status of this User. Returns the deleted status.
+      def delete_status
+        self.class.delete_status(self.client, self.id)
+        status
+      end
+
+      # Get a Collection of Group objects that represents all groups that this User is in. Always makes a call to the server.
+      def groups!
+        self.class.groups(self.client, self.id)
+      end
+
+      # Get a Collection of Group objects that represents all groups that this User is in. Returns cached data if it has been called before.
+      def groups
+        @groups ||= groups!
+      end
+
+      # Creates a new Subscription that represents this User following the resource with id _record_id_.
+      def follow(record_id)
+        self.class.follow(self.client, self.id, record_id)
+      end
+
+      # Get a Collection of Conversation objects that represents the conversations for this User. Always makes a call to the server.
+      def conversations!
+        self.class.conversations(self.client, self.id)
+      end
+
+      # Get a Collection of Conversation objects that represents the conversations for this User. Returns cached data if it has been called before.
+      def conversations
+        @conversations ||= conversations!
+      end
+
+      # Get a Collection of Message objects that represents the messages for this User. Always makes a call to the server.
+      def messages!
+        self.class.messages(self.client, self.id)
+      end
+
+      # Get a Collection of Message objects that represents the messages for this User. Returns cached data if it has been called before.
+      def messages
+        @messages ||= messages!
+      end
+    end
+  end
+end

data/lib/sfdc/client.rb

@@ -0,0 +1,98 @@
+require 'sfdc/client/connection'
+require 'sfdc/client/authentication'
+require 'sfdc/client/streaming'
+require 'sfdc/client/picklists'
+require 'sfdc/client/caching'
+require 'sfdc/client/canvas'
+require 'sfdc/client/api'
+
+module Sfdc
+  class Client
+    include Sfdc::Client::Connection
+    include Sfdc::Client::Authentication
+    include Sfdc::Client::Streaming
+    include Sfdc::Client::Picklists
+    include Sfdc::Client::Caching
+    include Sfdc::Client::Canvas
+    include Sfdc::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:
+    #   Sfdc::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:
+    #   Sfdc::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:
+    #   Sfdc::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[Sfdc.configuration.options.map { |option| [option, Sfdc.configuration.send(option)] }]
+      @options.merge! opts
+      yield builder if block_given?
+    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
+end

data/lib/sfdc/client/api.rb

@@ -0,0 +1,320 @@
+require 'sfdc/client/verbs'
+require 'sfdc/client/authentication'
+
+module Sfdc
+  class Client
+    module API
+      extend Sfdc::Client::Verbs
+
+      # 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.
+      define_verbs :get, :post, :put, :delete, :patch, :head
+
+      # 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.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 global describe for all sobjects
+      #   client.describe
+      #   # => { ... }
+      #
+      #   # get the describe for the Account object
+      #   client.describe('Account')
+      #   # => { ... }
+      #
+      # Returns the Hash representation of the describe call.
+      def describe(sobject = nil)
+        if sobject
+          api_get("sobjects/#{sobject.to_s}/describe").body
+        else
+          api_get('sobjects').body['sobjects']
+        end
+      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: Get the current user's Id.
+      # client.user_id
+      def user_id
+        response = authenticate!
+        info = get(response.id).body
+        user_id = info.user_id
+        return user_id
+      end
+
+      # Public: Executs a SOQL query and returns the result.
+      #
+      # soql - A SOQL expression.
+      #
+      # Examples
+      #
+      #   # Find the names of all Accounts
+      #   client.query('select Name from Account').map(&:Name)
+      #   # => ['Foo Bar Inc.', 'Whizbang Corp']
+      #
+      # Returns a Sfdc::Collection if Sfdc.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Sfdc.configuration.mashify is false.
+      def query(soql)
+        response = api_get 'query', :q => soql
+        mashify? ? response.body : response.body['records']
+      end
+
+      # Returns SFDC recent items Id.
+      def recent
+        response = api_get 'recent'
+        mashify? ? response.body : response.body['records']
+      end
+
+      # Public: Perform a SOSL search
+      #
+      # sosl - A SOSL expression.
+      #
+      # Examples
+      #
+      #   # Find all occurrences of 'bar'
+      #   client.search('FIND {bar}')
+      #   # => #<Sfdc::Collection >
+      #
+      #   # Find accounts match the term 'genepoint' and return the Name field
+      #   client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
+      #   # => ['GenePoint']
+      #
+      # Returns a Sfdc::Collection if Sfdc.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Sfdc.configuration.mashify is false.
+      def search(sosl)
+        api_get('search', :q => sosl).body
+      end
+
+      # Public: Insert a new record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new account
+      #   client.create('Account', Name: 'Foobar Inc.')
+      #   # => '0016000000MRatd'
+      #
+      # Returns the String Id of the newly created sobject.
+      # Returns false if something bad happens.
+      def create(*args)
+        create!(*args)
+      rescue *exceptions
+        false
+      end
+      alias_method :insert, :create
+
+      # Public: Insert a new record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new account
+      #   client.create!('Account', Name: 'Foobar Inc.')
+      #   # => '0016000000MRatd'
+      #
+      # Returns the String Id of the newly created sobject.
+      # Raises exceptions if an error is returned from Salesforce.
+      def create!(sobject, attrs)
+        api_post("sobjects/#{sobject}", attrs).body['id']
+      end
+      alias_method :insert!, :create!
+
+      # Public: Update a record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the Account with Id '0016000000MRatd'
+      #   client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+      #
+      # Returns true if the sobject was successfully updated.
+      # Returns false if there was an error.
+      def update(*args)
+        update!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Update a record.
+      #
+      # sobject - String name of the sobject.
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the Account with Id '0016000000MRatd'
+      #   client.update!('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+      #
+      # 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' })
+        raise 'Id field missing.' unless id
+        api_patch "sobjects/#{sobject}/#{id}", attrs
+        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(*args)
+        upsert!(*args)
+      rescue *exceptions
+        false
+      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.
+      # 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
+        (response.body && response.body['id']) ? response.body['id'] : true
+      end
+
+      # Public: Delete a record.
+      #
+      # sobject - String name of the sobject.
+      # id      - The Salesforce ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the Account with Id '0016000000MRatd'
+      #   client.destroy('Account', '0016000000MRatd')
+      #
+      # Returns true if the sobject was successfully deleted.
+      # Returns false if an error is returned from Salesforce.
+      def destroy(*args)
+        destroy!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Delete a record.
+      #
+      # sobject - String name of the sobject.
+      # id      - The Salesforce ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the Account with Id '0016000000MRatd'
+      #   client.destroy('Account', '0016000000MRatd')
+      #
+      # Returns true of the sobject was successfully deleted.
+      # Raises an exception if an error is returned from Salesforce.
+      def destroy!(sobject, id)
+        api_delete "sobjects/#{sobject}/#{id}"
+        true
+      end
+
+      # Public: Finds a single record and returns all fields.
+      #
+      # sobject - The String name of the sobject.
+      # id      - The id of the record. If field is specified, id should be the id
+      #           of the external field.
+      # field   - External ID field to use (default: nil).
+      #
+      # Returns the Sfdc::SObject sobject record.
+      def find(sobject, id, field=nil)
+        api_get(field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}").body
+      end
+
+
+      #################### Chatter items ############################
+      def feeds
+        api_get("/chatter/feeds/").body
+      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: Errors that should be rescued from in non-bang methods
+      def exceptions
+        [Faraday::Error::ClientError]
+      end
+
+    end
+  end
+end