databasedotcom 1.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+The 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.rdoc

@@ -0,0 +1,154 @@
+=databasedotcom
+databasedotcom is a gem to enable ruby applications to access the SalesForce REST API.  If you use bundler, simply list it in your Gemfile, like so:
+
+    gem 'databasedotcom'
+
+If you don't use bundler, install it by hand:
+
+    gem install databasedotcom
+
+=Documentation
+
+Reference documentation is available at rubydoc.info[http://rubydoc.info/github/heroku/databasedotcom/master/frames]
+
+=Source
+
+Source is available at github[http://github.com/heroku/databasedotcom]
+
+= Usage
+== Initialization
+When you create a Databasedotcom::Client object, you need to configure it with a client id and client secret that corresponds to one of the Remote Access Applications configured within your SalesForce instance.  The SalesForce UI refers to the client id as "Consumer Key", and to the client secret as "Consumer Secret".
+
+You can configure your Client object with a client id and client secret in one of several different ways:
+=== Configuration from the environment
+If configuration information is present in the environment, the new Client will take configuration information from there.
+
+    export DATABASEDOTCOM_CLIENT_ID=foo
+    export DATABASEDOTCOM_CLIENT_SECRET=bar
+
+Then
+
+    client = Databasedotcom::Client.new
+    client.client_id      #=> foo
+    client.client_secret  #=> bar
+
+=== Configuration from a YAML file
+If you pass the name of a YAML file when you create a Client, the new Client will read the YAML file and take the client id and client secret values from there.
+
+    # databasedotcom.yml
+    #
+    ---
+    client_secret: bro
+    client_id: baz
+
+Then
+
+    client = Databasedotcom::Client.new("databasedotcom.yml")
+    client.client_id      #=> bro
+    client.client_secret  #=> baz
+
+=== Configuration from a Hash
+If you pass a hash when you create a Client, the new Client will take configuration information from that Hash.
+
+    client = Databasedotcom::Client.new :client_id => "sponge", :client_secret => "bob"
+    client.client_id      #=> sponge
+    client.client_secret  #=> bob
+
+=== Configuration precedence
+Configuration information present in the environment always takes precedence over that passed in via a YAML file or a Hash.
+
+    export DATABASEDOTCOM_CLIENT_ID=foo
+    export DATABASEDOTCOM_CLIENT_SECRET=bar
+
+Then
+
+    client = Databasedotcom::Client.new :client_id => "sponge", :client_secret => "bob"
+    client.client_id      #=> foo
+    client.client_secret  #=> bar
+
+=== Usage in an application deployed on Heroku
+You can use the <tt>heroku config:add</tt> command to set environment variables:
+
+    heroku config:add DATABASEDOTCOM_CIENT_ID=foo
+    heroku config:add DATABASEDOTCOM_CIENT_SECRET=bar
+
+Then, when you create your client like:
+
+    client = Databasedotcom::Client.new
+
+it will use the configuration information that you set with <tt>heroku config:add</tt>.
+
+== Authentication
+The first thing you need to do with the new Client is to authenticate with SalesForce.  You can do this in one of several ways:
+
+=== Authentication via an externally-acquired OAuth access token
+If you have acquired an OAuth access token for your SalesForce instance through some external means, you can use it.  Note that you have to pass both the token and your SalesForce instance URL to the <tt>authenticate</tt> method:
+
+    client.authenticate :token => "my-oauth-token", :instance_url => "http://na1.salesforce.com"  #=> "my-oauth-token"
+
+=== Authentication via Omniauth
+If you are using the gem within the context of a web application, and your web app is using Omniauth to do OAuth with SalesForce, you can authentication the Client direction via the Hash that Omniauth passes to your OAuth callback method, like so:
+
+    client.authenticate request.env['omniauth.auth']  #=> "the-oauth-token"
+
+=== Authentication via username and password
+You can authenticate your Client directly with SalesForce with a valid username and password for a user in your SalesForce instance.  Note that, if access to your SalesForce instance requires a {security token}[http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_concepts_security.htm], the value that you pass for <tt>:password</tt> must be the password for the user concatenated with her security token.
+
+    client.authenticate :username => "foo@bar.com", :password => "ThePasswordTheSecurityToken"  #=> "the-oauth-token"
+
+== Accessing the Sobject API
+You can retrieve a list of Sobject defined in your SalesForce instance like so:
+
+    client.list_sobjects  #=> ['User', 'Group', 'Contact']
+
+Once you have the name of an Sobject, the easiest way to interact with it is to first materialize it:
+
+    contact_class = client.materialize("Contact") #=> Contact
+
+By default, Sobject classes are materialized into the global namespace- if you want materialize into another module, you can easily do configure this:
+
+    client.sobject_module = My::Module
+    client.materialize("Contact") #=> My::Module::Contact
+
+Materialized Sobject classes behave much like ActiveRecord classes:
+
+    contact = Contact.find("contact_id")                #=> #<Contact @Id="contact_id", ...>
+    contact = Contact.find_by_Name("John Smith")        #=> dynamic finders!
+    contacts = Contact.all                              #=> a Databasedotcom::Collection of Contact instances
+    contacts = Contact.find_all_by_Company("IBM")       #=> a Databasedotcom::Collection of matching Contacts
+    contact.Name                                        #=> the contact's Name attribute
+    contact["Name"]                                     #=> same thing
+    contact.Name = "new name"                           #=> change the contact's Name attribute, in memory
+    contact["Name"] = "new name"                        #=> same thing
+    contact.save                                        #=> save the changes to the database
+    contact.update_attributes "Name" => "newer name",
+      "Phone" => "4156543210"                           #=> change several attributes at once and save them
+    contact.delete                                      #=> delete the contact from the database
+
+See the documentation for full details.
+
+== Accessing the Chatter API
+You can easily access Chatter feeds, group, conversations, etc.:
+
+    my_feed_items = Databasedotcom::Chatter::UserProfileFeed.find(client)  #=> a Databasedotcom::Collection of FeedItems
+    
+    my_feed_items.each do |feed_item|
+      feed_item.likes                   #=> a Databasedotcom::Collection of Like instances
+      feed_item.comments                #=> a Databasedotcom::Collection of Comment instances
+      feed_item.raw_hash                #=> the hash returned from the Chatter API describing this FeedItem
+      feed_item.comment("This is cool") #=> create a new comment on the FeedItem
+      feed_item.like                    #=> the authenticating user likes the FeedItem
+    end
+
+    me = Databasedotcom::Chatter::User.find(client, "me")   #=> a User for the authenticating user
+    me.followers                                              #=> a Databasedotcom::Collection of Users
+    me.post_status("what I'm doing now")                      #=> post a new status
+    
+    you = Databasedotcom::Chatter::User.find(client, "your-user-id")
+    me.follow(you)                                            #=> start following a user
+
+See the documentation for full details.
+
+= License
+
+This gem is licensed under the MIT License.

data/lib/databasedotcom.rb

@@ -0,0 +1,7 @@
+require 'databasedotcom/version'
+require 'databasedotcom/core_extensions'
+require 'databasedotcom/client'
+require 'databasedotcom/sales_force_error'
+require 'databasedotcom/collection'
+require 'databasedotcom/sobject'
+require 'databasedotcom/chatter'

data/lib/databasedotcom/chatter.rb

@@ -0,0 +1,11 @@
+require 'databasedotcom/chatter/feeds'
+require 'databasedotcom/chatter/filter_feed'
+require 'databasedotcom/chatter/feed_item'
+require 'databasedotcom/chatter/comment'
+require 'databasedotcom/chatter/like'
+require 'databasedotcom/chatter/user'
+require 'databasedotcom/chatter/group'
+require 'databasedotcom/chatter/group_membership'
+require 'databasedotcom/chatter/subscription'
+require 'databasedotcom/chatter/conversation'
+require 'databasedotcom/chatter/message'

data/lib/databasedotcom/chatter/comment.rb

@@ -0,0 +1,10 @@
+require 'databasedotcom/chatter/record'
+
+module Databasedotcom
+  module Chatter
+
+    # A comment posted on a FeedItem.
+    class Comment < Record
+    end
+  end
+end

data/lib/databasedotcom/chatter/conversation.rb

@@ -0,0 +1,100 @@
+require 'databasedotcom/chatter/record'
+
+module Databasedotcom
+  module Chatter
+    # A thread of private messages. When calling +Conversation.find+ or +Conversation.all+, you must pass +:user_id => <my_user_id>+ in the _parameters_
+    #
+    #    Conversation.all(@client, :user_id => "me")
+    #    Conversation.find(@client, "conversationId", :user_id => "f80ad89f9d98d89dfd89")
+    class Conversation < Record
+
+      # Creates a new Conversation and sets its +id+ and +url+ to values obtained from the server response.
+      def initialize(client, response)
+        super
+        @id ||= @raw_hash["conversationId"]
+        @url ||= @raw_hash["conversationUrl"]
+      end
+
+      # Find the Conversation identified by _cid_ and archive it. Returns the updated Conversation.
+      #
+      #    Conversation.archive(@client, "fakeid")
+      def self.archive(client, cid)
+        url = "/services/data/v#{client.version}/chatter/users/me/conversations/#{cid}"
+        response = client.http_patch(url, nil, :archived => "true")
+        Conversation.new(client, response.body)
+      end
+
+      # Find the Conversation identified by _cid_ and unarchive it. Returns the updated Conversation.
+      #
+      #    Conversation.unarchive(@client, "fakeid")
+      def self.unarchive(client, cid)
+        url = "/services/data/v#{client.version}/chatter/users/me/conversations/#{cid}"
+        response = client.http_patch(url, nil, :archived => "false")
+        Conversation.new(client, response.body)
+      end
+
+      # Find the Conversation identified by _cid_ and mark it as read. Returns the updated Conversation.
+      #
+      #    Conversation.mark_read(@client, "fakeid")
+      def self.mark_read(client, cid)
+        url = "/services/data/v#{client.version}/chatter/users/me/conversations/#{cid}"
+        response = client.http_patch(url, nil, :read => "true")
+        Conversation.new(client, response.body)
+      end
+
+      # Find the Conversation identified by _cid_ and mark it as unread. Returns the updated Conversation.
+      #
+      #    Conversation.mark_unread(@client, "fakeid")
+      def self.mark_unread(client, cid)
+        url = "/services/data/v#{client.version}/chatter/users/me/conversations/#{cid}"
+        response = client.http_patch(url, nil, :read => "false")
+        Conversation.new(client, response.body)
+      end
+
+      # Gets all messages for the Conversation specified by _cid_ and the User specified by _uid_. Returns a Collection of Message objects.
+      def self.messages(client, uid, cid)
+        conversation = self.find(client, cid, :user_id => uid)
+        collection = Databasedotcom::Collection.new(client, nil, conversation.raw_hash["messages"]["nextPageUrl"], conversation.raw_hash["messages"]["previousPageUrl"], conversation.raw_hash["messages"]["currentPageUrl"])
+        conversation.raw_hash["messages"]["messages"].each do |item|
+          collection << Message.new(client, item)
+        end
+        collection
+      end
+
+      # Archive this Conversation.
+      def archive
+        self.class.archive(self.client, self.id)
+      end
+
+      # Unarchive this Conversation.
+      def unarchive
+        self.class.unarchive(self.client, self.id)
+      end
+
+      # Mark this Conversation as read.
+      def mark_read
+        self.class.mark_read(self.client, self.id)
+      end
+
+      # Mark this Conversation as unread.
+      def mark_unread
+        self.class.mark_unread(self.client, self.id)
+      end
+
+      # Return a Collection of messages from this Conversation.
+      def messages
+        collection = Databasedotcom::Collection.new(client, nil, self.raw_hash["messages"]["nextPageUrl"], self.raw_hash["messages"]["previousPageUrl"], self.raw_hash["messages"]["currentPageUrl"])
+        self.raw_hash["messages"]["messages"].each do |item|
+          collection << Message.new(client, item)
+        end
+        collection
+      end
+
+      protected
+
+      def self.search_parameter_name
+        :Q
+      end
+    end
+  end
+end

data/lib/databasedotcom/chatter/feed.rb

@@ -0,0 +1,64 @@
+require 'json'
+
+module Databasedotcom
+  module Chatter
+    # Parent class of all feeds and inherits from Collection. This class is not intended to be instantiated. Methods should be called on subclasses, which are all are dynamically defined (except for FilterFeed). Defined feeds are *NewsFeed*, *UserProfileFeed*, *RecordFeed*, *ToFeed*, *PeopleFeed*, *GroupsFeed*, *FilesFeed*, *CompanyFeed*, and *FilterFeed*.
+    class Feed < Collection
+
+      # Returns an enumerable Feed of FeedItem objects that make up the feed with the specified _id_. Should not be called as a class method on Feed, but as a method on subclasses.
+      #
+      #    NewsFeed.find(@client)                   #=>   [#<FeedItem ...>, #<FeedItem ...>, ...]
+      #    PeopleFeed.find(@client, "userid")       #=>   [#<FeedItem ...>, #<FeedItem ...>, ...]
+      #    FilterFeed.find(@client, "me", "000")    #=>   [#<FeedItem ...>, #<FeedItem ...>, ...]
+      #
+      # _id_prefix_ is only applicable for FilterFeed.
+      def self.find(client, id="me", id_prefix=nil)
+        path_components = %w(services data)
+        path_components << "v#{client.version}"
+        path_components.concat(%w(chatter feeds))
+        path_components << feed_type
+        path_components << id unless feed_type == "company"
+        path_components << id_prefix
+        path_components << "feed-items"
+        path = "/" + path_components.compact.join('/')
+        result = client.http_get(path)
+        response = JSON.parse(result.body)
+        collection = self.new(client, nil, response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        response["items"].each do |item|
+          collection << FeedItem.new(client, item)
+        end
+        collection
+      end
+
+      # Posts a FeedItem to a Feed specified by _user_id_. Should not be called as a class method on Feed, but as a method on subclasses.
+      #
+      #    UserProfileFeed.post(@client, "me", :text => "This is a status update about Salesforce.", :url => "http://www.salesforce.com")
+      #
+      # Returns the newly created FeedItem.
+      def self.post(client, user_id, parameters)
+        url = "/services/data/v#{client.version}/chatter/feeds/#{feed_type}/#{user_id}/feed-items"
+        response = client.http_post(url, nil, parameters)
+        Databasedotcom::Chatter::FeedItem.new(client, response.body)
+      end
+
+      # Posts a file to a Feed specified by _user_id_. Should not be called as a class method on Feed, but as a method on subclasses.
+      #
+      #    UserProfileFeed.post_file(@client, "me", File.open("MyFile"), "text/plain", "MyFile", :desc => "This is an uploaded text file.")
+      #
+      # Returns the newly created FeedItem.
+      def self.post_file(client, user_id, io, file_type, file_name, parameters={})
+        url = "/services/data/v#{client.version}/chatter/feeds/#{feed_type}/#{user_id}/feed-items"
+        response = client.http_multipart_post(url, {"feedItemFileUpload" => UploadIO.new(io, file_type, file_name), "fileName" => file_name}, parameters)
+        Databasedotcom::Chatter::FeedItem.new(client, response.body)
+      end
+
+      private
+
+      def self.feed_type
+        self.name.match(/.+::(.+)Feed$/)[1].resourcerize
+      end
+    end
+
+    FEED_TYPES = %w(News UserProfile Record To People Groups Files Company)
+  end
+end

data/lib/databasedotcom/chatter/feed_item.rb

@@ -0,0 +1,40 @@
+require 'databasedotcom/chatter/record'
+
+module Databasedotcom
+  module Chatter
+
+    # An item in a Feed.
+    class FeedItem < Record
+
+      # Returns a Collection of comments that were posted on this FeedItem instance.
+      def comments
+        collection = Databasedotcom::Collection.new(self.client, self.raw_hash["comments"]["total"], self.raw_hash["comments"]["nextPageUrl"], nil, self.raw_hash["comments"]["currentPageUrl"])
+        collection.concat(self.raw_hash["comments"]["comments"])
+      end
+
+      # Returns a Collection of likes for this FeedItem instance.
+      def likes
+        collection = Databasedotcom::Collection.new(self.client, self.raw_hash["likes"]["total"], self.raw_hash["likes"]["nextPageUrl"], self.raw_hash["likes"]["previousPageUrl"], self.raw_hash["likes"]["currentPageUrl"])
+        collection.concat(self.raw_hash["likes"]["likes"])
+      end
+
+      # Like this FeedItem.
+      def like
+        result = self.client.http_post("/services/data/v#{self.client.version}/chatter/feed-items/#{self.id}/likes")
+        Like.new(self.client, result.body)
+      end
+
+      # Post a Comment on this FeedItem with content _text_.
+      def comment(text)
+        result = self.client.http_post("/services/data/v#{self.client.version}/chatter/feed-items/#{self.id}/comments", nil, :text => text)
+        Comment.new(self.client, result.body)
+      end
+
+      protected
+
+      def self.collection_from_response(response)
+        response["items"]
+      end
+    end
+  end
+end

data/lib/databasedotcom/chatter/feeds.rb

@@ -0,0 +1,5 @@
+require 'databasedotcom/chatter/feed'
+
+Databasedotcom::Chatter::FEED_TYPES.each do |feed_type|
+  Databasedotcom::Chatter.const_set("#{feed_type}Feed", Class.new(Databasedotcom::Chatter::Feed))
+end

data/lib/databasedotcom/chatter/filter_feed.rb

@@ -0,0 +1,14 @@
+module Databasedotcom
+  module Chatter
+    # Filter feeds contain items pertaining to both a user and another specified resource.
+    class FilterFeed < Feed
+
+      # Lists all FilterFeeds for the user with id _user_id_.
+      def self.feeds(client, user_id="me")
+        url = "/services/data/v#{client.version}/chatter/feeds/filter/#{user_id}"
+        result = client.http_get(url)
+        JSON.parse(result.body)
+      end
+    end
+  end
+end

data/lib/databasedotcom/chatter/group.rb

@@ -0,0 +1,45 @@
+require 'databasedotcom/chatter/record'
+require 'databasedotcom/chatter/photo_methods'
+
+module Databasedotcom
+  module Chatter
+    # A group of Users
+    class Group < Record
+      include PhotoMethods
+
+      # Returns a Collection of GroupMembership instances for the Group identified by _group_id_.
+      def self.members(client, group_id)
+        url = "/services/data/v#{client.version}/chatter/groups/#{group_id}/members"
+        result = client.http_get(url)
+        response = JSON.parse(result.body)
+        collection = Databasedotcom::Collection.new(client, response["totalMemberCount"], response["nextPageUrl"], response["previousPageUrl"], response["currentPageUrl"])
+        response["members"].each do |member|
+          collection << GroupMembership.new(client, member)
+        end
+        collection
+      end
+
+      # Join the group identified by _group_id_ as the user identified by _user_id_.
+      def self.join(client, group_id, user_id="me")
+        url = "/services/data/v#{client.version}/chatter/groups/#{group_id}/members"
+        response = client.http_post(url, nil, :userId => user_id)
+        GroupMembership.new(client, response.body)
+      end
+
+      # Get a Collection of GroupMembership objects for this Group. Always makes a call to the server.
+      def members!
+        self.class.members(self.client, self.id)
+      end
+
+      # Get a Collection of GroupMembership objects for this Group. Returns cached data if it has been called before.
+      def members
+        @members ||= members!
+      end
+
+      # Join this Group as the user identified by _user_id_.
+      def join(user_id="me")
+        self.class.join(self.client, self.id, user_id)
+      end
+    end
+  end
+end