intercom 0.0.4 → 0.0.5

data/.gitignore

@@ -1,3 +1,4 @@
+doc
 *.gem
 *.iml
 .bundle

data/changes.txt

@@ -0,0 +1,15 @@
+0.0.5
+ - added Intercom::User.find_by_email, Intercom::User.find_by_user_id
+ - add support for Intercom::User.all.each, Intercom::User.all.map, Intercom::User.all.count
+
+0.0.4
+ - allow to directly set custom_data hash on Intercom::User user.custom_data = {...}
+
+0.0.3
+ - renamed Intercom.secret_key to Intercom.api_key for consistency throughout our app and docs
+
+0.0.2
+ - updates to reflect changes to resources served by the api
+
+0.0.1
+ - experimental version

data/lib/intercom.rb

@@ -67,7 +67,7 @@ module Intercom
   end
 
   def self.execute_request(method, path, params = {}, headers = {}, payload = nil)
-    method.eql?(:get) ? require_email_or_user_id(params) : require_email_or_user_id(payload)
+    method.eql?(:get) ? require_email_or_user_id(params) : require_email_or_user_id(payload) unless path.eql?("users")
     args =rest_client_args(method, path, params, headers, payload)
     begin
       response = RestClient::Request.execute(args)

data/lib/intercom/user.rb

@@ -1,11 +1,26 @@
 require 'intercom/user_resource'
-require 'intercom/shallow_hash'
+require 'intercom/user_custom_data'
+require 'intercom/user_collection_proxy'
 require 'intercom/social_profile'
 
 module Intercom
-  ##
   # Represents a user of your application on Intercom.
-  class User < UserResource
+  #
+  # == Example usage
+  # * Fetching a user
+  #    Intercom::User.find_by_email("bob@example.")
+  #
+  # * Getting the count of all users
+  #    Intercom::User.all.count
+  #
+  # * Fetching all users
+  #    Intercom::User.all.each {|user| puts user.email }
+  #
+  # * Updating custom data on a user
+  #    user = Intercom::User.find_by_email("bob@example.com")
+  #    user.custom_data["number_of_applications"] = 11
+  #    user.save
+class User < UserResource
     ##
     # Fetches an Intercom::User from our API.
     #
@@ -19,7 +34,26 @@ module Intercom
       User.from_api(response)
     end
 
-    ##
+    # Calls GET https://api.intercom.io/v1/users?email=EMAIL
+    #
+    # returns Intercom::User object representing the state on our servers.
+    #
+    # @param [String] email address of the user
+    # @return [User]
+    def self.find_by_email(email)
+      find({:email => email})
+    end
+
+    # Calls GET https://api.intercom.io/v1/users?user_id=USER-ID
+    #
+    # returns Intercom::User object representing the state on our servers.
+    #
+    # @param [String] user_id user id of the user
+    # @return [User]
+    def self.find_by_user_id(user_id)
+      find({:user_id => user_id})
+    end
+
     # Creates (or updates when a user already exists for that email/user_id) a user record on your application.
     #
     # Calls POST https://api.intercom.io/v1/users
@@ -32,6 +66,22 @@ module Intercom
       User.new(params).save
     end
 
+    # Retrieve all the users
+    # Examples:
+    #   Intercom::User.all.count
+    #     > 5346
+    #   Intercom::User.each do |user|
+    #     puts user.inspect
+    #   end
+    #     > ["user1@example.com" ,"user2@example.com" ,....]
+    #   Intercom::User.map(&:email)
+    #     > ["user1@example.com" ,"user2@example.com" ,....]
+    #
+    # @return [UserCollectionProxy]
+    def self.all
+      UserCollectionProxy.new
+    end
+
     # instance method alternative to #create
     # @return [User]
     def save
@@ -39,11 +89,13 @@ module Intercom
       self.update_from_api_response(response)
     end
 
-    # @return {User}
+    # @return [String] the {User}'s name
     def name
       @attributes["name"]
     end
 
+    # @param [String] name {User}'s name
+    # @return [void]
     def name=(name)
       @attributes["name"]=name
     end
@@ -53,6 +105,7 @@ module Intercom
       @attributes["last_seen_ip"]
     end
 
+    # @return [void]
     def last_seen_ip=(last_seen_ip)
       @attributes["last_seen_ip"]=last_seen_ip
     end
@@ -62,6 +115,7 @@ module Intercom
       @attributes["last_seen_user_agent"]
     end
 
+    # @return [void]
     def last_seen_user_agent=(last_seen_user_agent)
       @attributes["last_seen_user_agent"]=last_seen_user_agent
     end
@@ -92,6 +146,7 @@ module Intercom
 
     ##
     # Set Time at which this User started using your application.
+    # @return [void]
     def created_at=(time)
       set_time_at("created_at", time)
     end
@@ -120,17 +175,30 @@ module Intercom
       @location_data ||= {}.freeze
     end
 
-    ##
-    # Get hash of custom attributes stored for this Intercom::User
+    # Custom attributes stored for this Intercom::User
     #
     # See http://docs.intercom.io/#CustomData for more information
-    # @return [Hash]
+    #
+    # Example: Reading custom_data value for an existing user
+    #  user = Intercom::User.find(:email => "someone@example.com")
+    #  puts user.custom_data[:plan]
+    #
+    # Example: Setting some custom data for an existing user
+    #  user = Intercom::User.find(:email => "someone@example.com")
+    #  user.custom_data[:plan] = "pro"
+    #  user.save
+    #
+    # @return [UserCustomData]
     def custom_data
-      @attributes["custom_data"] ||= ShallowHash.new
+      @attributes["custom_data"] ||= UserCustomData.new
     end
 
-    def custom_data=(custom_data) #:nodoc:
-      @attributes["custom_data"] = ShallowHash.new.merge(custom_data)
+    # Set a {Hash} of custom data attributes to save/update on this user
+    #
+    # @param [Hash] custom_data
+    # @return [UserCustomData]
+    def custom_data=(custom_data)
+      @attributes["custom_data"] = UserCustomData.new(custom_data)
     end
 
     protected

data/lib/intercom/user_collection_proxy.rb

@@ -0,0 +1,51 @@
+require 'intercom/user_resource'
+require 'intercom/user_custom_data'
+require 'intercom/social_profile'
+
+module Intercom
+  # A collection of your Users from Intercom
+  # Uses the paginated users api under the covers (http://docs.intercom.io/api#getting_all_users)
+  #
+  # == Examples:
+  #
+  # Fetching a count of all Users tracked on Intercom
+  #    Intercom::User.all.count
+  #
+  # Iterating over each user
+  #    Intercom::User.each do |user|
+  #      puts user.inspect
+  #    end
+  #
+  class UserCollectionProxy
+    # @return [Integer] number of users tracked on Intercom for this application
+    def count
+      response = Intercom.get("users", {:per_page => 1})
+      response["total_count"]
+    end
+
+    # yields each {User} to the block provided
+    # @return [void]
+    def each(&block)
+      page = 1
+      fetch_another_page = true
+      while fetch_another_page
+        current_page = Intercom.get("users", {:page => page})
+        current_page["users"].each do |user|
+          block.call User.from_api(user)
+        end
+        page = page + 1
+        fetch_another_page = !current_page["next_page"].nil?
+      end
+    end
+
+    # yields each {User} to the block provided and collects the output in the same way as Enumerable#map
+    # @return [Array<Object>]
+    def map
+      out = []
+      each { |e| out << yield(e) }
+      out
+    end
+
+    alias :collect :map
+  end
+end

data/lib/intercom/user_custom_data.rb

@@ -0,0 +1,27 @@
+module Intercom
+  # Sub-class of {Hash} for storing custom data attributes.
+  # Doesn't allow nested Hashes or Arrays. And requires {String} or {Symbol} keys.
+  class UserCustomData < Hash
+    def initialize(attributes={})
+      (attributes).each do |key, value|
+        validate_key_and_value(key, value)
+        self[key] = value
+      end
+    end
+
+    def []=(key, value)
+      validate_key_and_value(key, value)
+      super(key.to_s, value)
+    end
+
+    def [](key)
+      super(key.to_s)
+    end
+
+    private
+    def validate_key_and_value(key, value)
+      raise ArgumentError.new("custom_data does not support nested data structures (key: #{key}, value: #{value}") if value.is_a?(Array) || value.is_a?(Hash)
+      raise ArgumentError.new("custom_data key must be String or Symbol: #{key}") unless key.is_a?(String) || key.is_a?(Symbol)
+    end
+  end
+end

data/lib/intercom/version.rb

@@ -1,3 +1,3 @@
 module Intercom #:nodoc:
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/unit/intercom/user_collection_proxy_spec.rb

@@ -0,0 +1,32 @@
+require "spec_helper"
+
+describe Intercom::UserCollectionProxy do
+  before :each do
+    Intercom.expects(:execute_request).never
+  end
+
+  it "supports each" do
+    Intercom.expects(:get).with("users", {:page => 1}).returns(page_of_users)
+    emails = []
+    Intercom::User.all.each { |user| emails << user.email }
+    emails.must_equal %W(user1@example.com user2@example.com user3@example.com)
+  end
+
+  it "supports map" do
+    Intercom.expects(:get).with("users", {:page => 1}).returns(page_of_users).twice
+    Intercom::User.all.map { |user| user.email }.must_equal %W(user1@example.com user2@example.com user3@example.com)
+    Intercom::User.all.collect { |user| user.email }.must_equal %W(user1@example.com user2@example.com user3@example.com)
+  end
+
+  it "yields each user to the block" do
+    Intercom.expects(:get).with("users", {:per_page => 1}).returns(page_of_users(1,1))
+    Intercom::User.all.count.must_equal 3
+  end
+
+  it "loads multiple pages" do
+    Intercom.expects(:get).with("users", {:page => 1}).returns(page_of_users(1, 1))
+    Intercom.expects(:get).with("users", {:page => 2}).returns(page_of_users(2, 1))
+    Intercom.expects(:get).with("users", {:page => 3}).returns(page_of_users(3, 1))
+    Intercom::User.all.map { |user| user.email }.must_equal %W(user1@example.com user2@example.com user3@example.com)
+  end
+end

data/spec/unit/intercom/user_custom_data_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+describe Intercom::UserCustomData do
+  it "raises if you try to set or merge in nested hash structures" do
+    data = Intercom::UserCustomData.new()
+    proc { data["thing"] = [1] }.must_raise ArgumentError
+    proc { data["thing"] = {1 => 2} }.must_raise ArgumentError
+    proc { Intercom::UserCustomData.new({1 => {2 => 3}}) }.must_raise ArgumentError
+  end
+
+  it "raises if you try to use a non string key" do
+    data = Intercom::UserCustomData.new()
+    proc { data[1] = "something" }.must_raise ArgumentError
+  end
+
+  it "sets and merges valid entries" do
+    data = Intercom::UserCustomData.new()
+    data["a"] = 1
+    data[:b] = 2
+    data[:a].must_equal 1
+    data["b"].must_equal 2
+    data[:b].must_equal 2
+    data = Intercom::UserCustomData.new({"a" => 1, :b => 2})
+    data["a"].must_equal 1
+    data[:a].must_equal 1
+    data["b"].must_equal 2
+    data[:b].must_equal 2
+  end
+end

data/spec/unit/intercom/user_spec.rb

@@ -77,6 +77,7 @@ describe "Intercom::User" do
     user = Intercom::User.new()
     proc { user.custom_data["thing"] = [1] }.must_raise ArgumentError
     proc { user.custom_data["thing"] = {1 => 2} }.must_raise ArgumentError
+    proc { user.custom_data = {1 => {2 => 3}} }.must_raise ArgumentError
 
     user = Intercom::User.from_api(test_user)
     proc { user.custom_data["thing"] = [1] }.must_raise ArgumentError
@@ -85,7 +86,7 @@ describe "Intercom::User" do
   it "fetches a user" do
     Intercom.expects(:get).with("users", {"email" => "bo@example.com"}).returns(test_user)
     user = Intercom::User.find("email" => "bo@example.com")
-    user.email.must_equal "bo@example.com"
+    user.email.must_equal "bob@example.com"
     user.name.must_equal "Joe Schmoe"
     user.session_count.must_equal 123
   end
@@ -121,7 +122,7 @@ describe "Intercom::User" do
     params = {"email" => "me@example.com", :user_id => "abc123", "name" => "Bob Smith", "last_seen_ip" => "1.2.3.4", "last_seen_user_agent" => "ie6", "created_at" => Time.now}
     user = Intercom::User.new(params)
     user.to_hash.keys.sort.must_equal params.keys.map(&:to_s).sort
-    params.keys.each do | key|
+    params.keys.each do |key|
       user.send(key).to_s.must_equal params[key].to_s
     end
   end
@@ -130,4 +131,20 @@ describe "Intercom::User" do
     user = Intercom::User.send(:from_api, {"new_param" => "some value"})
     user.new_param.must_equal "some value"
   end
+
+  it "returns a UserCollectionProxy for all without making any requests" do
+    Intercom.expects(:execute_request).never
+    all = Intercom::User.all
+    all.must_be_instance_of(Intercom::UserCollectionProxy)
+  end
+
+  it "can find_by_email" do
+    Intercom::User.expects(:find).with(:email => "bob@example.com")
+    Intercom::User.find_by_email("bob@example.com")
+  end
+
+  it "can find_by_user_id" do
+    Intercom::User.expects(:find).with(:user_id => "abc123")
+    Intercom::User.find_by_user_id("abc123")
+  end
 end

data/spec/unit/intercom_spec.rb

@@ -2,7 +2,7 @@ require "spec_helper"
 
 describe Intercom do
   it "has a version number" do
-    Intercom::VERSION.must_match /\d+\.\d+\.\d+/
+    Intercom::VERSION.must_match(/\d+\.\d+\.\d+/)
   end
 
   describe "API" do
@@ -47,9 +47,9 @@ describe Intercom do
   it "checks for email or user id" do
     proc { Intercom.require_email_or_user_id("else") }.must_raise ArgumentError, "Expected params Hash, got String"
     proc { Intercom.require_email_or_user_id(:something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
-    proc { Intercom.get("users", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
-    proc { Intercom.put("users", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
-    proc { Intercom.post("users", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
+    proc { Intercom.get("messages", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
+    proc { Intercom.put("messages", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
+    proc { Intercom.post("messages", :something => "else") }.must_raise ArgumentError, "Either email or user_id must be specified"
     Intercom.require_email_or_user_id(:email => "bob@example.com", :something => "else")
     Intercom.require_email_or_user_id("email" => "bob@example.com", :something => "else")
     Intercom.require_email_or_user_id(:user_id => "123")

data/spec/unit/spec_helper.rb

@@ -2,16 +2,16 @@ require 'intercom'
 require 'minitest/autorun'
 require 'mocha'
 
-def test_user
+def test_user(email="bob@example.com")
   {
       :user_id => 'id-from-customers-app',
-      :email => "bo@example.com",
+      :email => email,
       :name => "Joe Schmoe",
       :created_at => 1323422442,
-      :last_seen_ip  => "1.2.3.4",
-      :last_seen_user_agent  => "Mozilla blah blah ie6",
+      :last_seen_ip => "1.2.3.4",
+      :last_seen_user_agent => "Mozilla blah blah ie6",
       :custom_data => {"a" => "b", "b" => 2},
-      :relationship_score  => 90,
+      :relationship_score => 90,
       :session_count => 123,
       :last_impression_at => 1323422442,
       :social_profiles => [
@@ -71,6 +71,22 @@ def test_message
   }
 end
 
+def page_of_users(page=1, per_page=10)
+  all_users = [test_user("user1@example.com"), test_user("user2@example.com"), test_user("user3@example.com")]
+  offset = (page - 1) * per_page
+  limit = page * per_page
+  next_page = limit < all_users.size ? page + 1 : nil
+  previous_page = offset > 0 ? page - 1 : nil
+  {
+      "users" => all_users[offset..limit-1],
+      "total_count" => all_users.size,
+      "page" => page,
+      "next_page" => next_page,
+      "previous_page" => previous_page,
+      "total_pages" => (all_users.size.to_f / per_page).ceil.to_i
+  }
+end
+
 def capture_exception(&block)
   begin
     block.call

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intercom
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-09 00:00:00.000000000Z
+date: 2012-03-13 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70301913505580 !ruby/object:Gem::Requirement
+  requirement: &70170925085820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70301913505580
+  version_requirements: *70170925085820
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70301913504840 !ruby/object:Gem::Requirement
+  requirement: &70170925084400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70301913504840
+  version_requirements: *70170925084400
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70301913504220 !ruby/object:Gem::Requirement
+  requirement: &70170925083440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70301913504220
+  version_requirements: *70170925083440
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70301913503620 !ruby/object:Gem::Requirement
+  requirement: &70170925082380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,7 +56,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70301913503620
+  version_requirements: *70170925082380
 description: ! 'Intercom (https://www.intercom.io) is a customer relationship management
   and messaging tool for web app owners. This library wraps the api provided by Intercom.
   See http://docs.intercom.io/api for more details. '
@@ -73,21 +73,24 @@ files:
 - LICENSE
 - README.rdoc
 - Rakefile
-- changed.txt
+- changes.txt
 - intercom.gemspec
 - lib/data/cacert.pem
 - lib/intercom.rb
 - lib/intercom/impression.rb
 - lib/intercom/message_thread.rb
-- lib/intercom/shallow_hash.rb
 - lib/intercom/social_profile.rb
 - lib/intercom/unix_timestamp_unwrapper.rb
 - lib/intercom/user.rb
+- lib/intercom/user_collection_proxy.rb
+- lib/intercom/user_custom_data.rb
 - lib/intercom/user_resource.rb
 - lib/intercom/version.rb
 - spec/integration/intercom_api_integration_spec.rb
 - spec/unit/intercom/impression_spec.rb
 - spec/unit/intercom/message_thread_spec.rb
+- spec/unit/intercom/user_collection_proxy_spec.rb
+- spec/unit/intercom/user_custom_data_spec.rb
 - spec/unit/intercom/user_resource_spec.rb
 - spec/unit/intercom/user_spec.rb
 - spec/unit/intercom_spec.rb
@@ -120,7 +123,10 @@ test_files:
 - spec/integration/intercom_api_integration_spec.rb
 - spec/unit/intercom/impression_spec.rb
 - spec/unit/intercom/message_thread_spec.rb
+- spec/unit/intercom/user_collection_proxy_spec.rb
+- spec/unit/intercom/user_custom_data_spec.rb
 - spec/unit/intercom/user_resource_spec.rb
 - spec/unit/intercom/user_spec.rb
 - spec/unit/intercom_spec.rb
 - spec/unit/spec_helper.rb
+has_rdoc: 

data/changed.txt

@@ -1,8 +0,0 @@
-0.0.3
- - renamed Intercom.secret_key to Intercom.api_key for consistency throughout our app and docs
-
-0.0.2
- - updates to reflect changes to resources served by the api
-
-0.0.1
- - experimental version

data/lib/intercom/shallow_hash.rb

@@ -1,9 +0,0 @@
-module Intercom
-  # Sub-class of {Hash} which doesn't allow {Array} or {Hash} values.
-  class ShallowHash < Hash
-    def []=(key, value)
-      raise ArgumentError.new("custom_data does not support nested data structures (key: #{key}, value: #{value}") if value.is_a?(Array) || value.is_a?(Hash)
-      super(key, value)
-    end
-  end
-end