Merge pull request #63 from intercom/user-event-release

Add user events

Author: josler

changes.txt

@@ -1,3 +1,6 @@
+0.2.0
+- Add UserEvents.
+
 0.1.19
 - Update DELETE request to fix issue.
 

lib/intercom.rb

@@ -6,6 +6,7 @@
 require "intercom/note"
 require "intercom/tag"
 require "intercom/request"
+require "intercom/user_event"
 require "json"
 
 ##

lib/intercom/request.rb

@@ -62,7 +62,7 @@ def execute(target_base_url=nil)
         response = http.request(net_http_method)
         raise_errors_on_failure(response)
         decoded = decode(response['content-encoding'], response.body)
-        JSON.parse(decoded)
+        JSON.parse(decoded) unless decoded.empty?
       end
     rescue Timeout::Error
       raise Intercom::ServiceUnavailableError

lib/intercom/user.rb

@@ -335,6 +335,16 @@ def companies=(companies)
       raise ArgumentError.new("Companies requires an array of hashes of companies") unless companies.is_a?(Array) && companies.all? {|company| company.is_a?(Hash)}
       @attributes["companies"] = companies.collect {|company| FlatStore.new(company) }
     end
+    
+    ##
+    # Creates a UserEvent for the given User
+    # @param {Hash} options, keys for :created (Unix timestamp) and :company_id (String)
+    def log_event(event_name, options={})
+      attributes = {:event_name => event_name, :user => self}
+      attributes[:created] = options[:created] unless options[:created].nil?
+      attributes[:company_id] = options[:company_id] unless options[:company_id].nil? 
+      UserEvent.create(attributes)
+    end
 
     protected
       def social_profiles=(social_profiles) #:nodoc:

lib/intercom/user_event.rb

@@ -0,0 +1,102 @@
+require 'intercom/requires_parameters'
+require 'intercom/hashable_object'
+
+
+module Intercom
+  
+  ##
+  # Represents a User Event
+  #
+  # A user event consists of an event_name and a user the event applies to. The user is identified via email or id.
+  # Additionally, a created timestamp is required.
+  #
+  # == Examples
+  #
+  #  user_event = Intercom::UserEvent.create(:event_name => "post", :user => current_user, :created => Time.now)
+  #
+  #  You can also create an user-event and save it like this:
+  #  user_event = Intercom::UserEvent.new
+  #  user_event.event_name = "publish-post"
+  #  user_event.user = current_user
+  #  user_event.created = Time.now
+  #  user_event.metadata = {
+  #   :title => 'Gravity Review',
+  #   :link => 'https://example.org/posts/22',
+  #   :comments => 'https://example.org/posts/22/comments'
+  # }
+  #  user_event.save
+  #
+  # == Batch
+  #
+  # User events can be created in batches, and sent as one request. To do some, create user events
+  # without calling .create, as follows:
+  # 
+  # user_event = Intercom::UserEvent.new
+  # user_event.event_name = "publish-post"
+  # user_event.user = current_user
+  #
+  # Then pass them to the save_batch_events class method, along with an (optional) default user:
+  #
+  # Intercom::UserEvent.save_batch_events(events, default_user)
+  #
+  # Any events without a user will be assigned to the default_user.
+  #
+  # Note: if you do not supply a created time, the current time in UTC will be used. Events that have the same 
+  # user, name, and created time (to second granularity) may be treated as duplicates by the server.
+  
+  class UserEvent
+    extend RequiresParameters
+    include HashableObject
+    
+    attr_accessor :event_name, :user, :created_at # required
+    attr_accessor :metadata, :type
+    
+    def initialize(attributes={})
+      from_hash(attributes)
+    end
+    
+    ##
+    # Creates a new User Event using params and saves it
+    # @see #save
+    def self.create(params)
+      params[:created_at] ||= Time.now
+      requires_parameters(params, %W(event_name user created_at))
+      UserEvent.new(params).save
+    end
+        
+    ##
+    # Save the User Event
+    def save
+      raise ArgumentError.new("Missing User") if user.nil?
+      UserEvent.save_batch_events([self])
+      self
+    end
+    
+    ##
+    # Save a list of User Events, with an optional base_user
+    def self.save_batch_events(events, base_user=nil)
+      hash = { :type => 'event.list', :data => []}
+      hash[:user] = { :user_id => base_user.user_id } if base_user
+      events.each do |event|
+        hash[:data] << event.event_hash
+      end
+      post_to_intercom(hash)
+    end
+
+    def self.post_to_intercom(hash)
+      Intercom.post('/events', hash)
+    end
+        
+    def user_hash
+      { :user_id => user.user_id }
+    end
+    
+    def event_hash
+      event = { :event_name => event_name, :created => created_at.nil? ?  Time.now.utc.to_i : created_at.to_i }
+      event[:type] = type.nil? ? 'event' : type
+      event[:user] = user_hash unless user.nil?
+      event[:metadata] = metadata unless metadata.nil?
+      event
+    end
+  end
+end

lib/intercom/version.rb

@@ -1,3 +1,3 @@
 module Intercom #:nodoc:
-  VERSION = "0.1.19"
+  VERSION = "0.2.0"
 end

spec/integration/intercom_api_integration_spec.rb

@@ -69,7 +69,37 @@ def fixture(name)
     note.html.must_equal "<p>This is a note</p>"
     note.user.email.must_equal "[email protected]"
   end
-
+  
+  it "should create a user event" do
+    FakeWeb.register_uri(:get, %r(v1/users\?email=), :body => fixture('v1-user'))
+    user = Intercom::User.find(:email => "[email protected]")
+    FakeWeb.register_uri(:post, %r(/events), :status => ["202", "Created"])
+    Intercom::UserEvent.create(:event_name => "signup", :created_at => 1391691571, :user => user).event_name.must_equal "signup"
+  end
+  
+  it "should create batch user events" do
+    FakeWeb.register_uri(:get, %r(v1/users\?email=), :body => fixture('v1-user'))
+    user = Intercom::User.find(:email => "[email protected]")
+    
+    first_event = Intercom::UserEvent.new
+    first_event.event_name = "first event"
+    first_event.created_at = Time.now
+    first_event.user = user
+    
+    second_event = Intercom::UserEvent.new
+    second_event.event_name = "second event"
+    second_event.created_at = Time.now
+    
+    FakeWeb.register_uri(:post, %r(/events), :status => ["202", "Created"])
+    Intercom::UserEvent.save_batch_events([first_event, second_event], user)
+  end
+  
+  it "should create a user event from a user" do
+    FakeWeb.register_uri(:get, %r(v1/users\?email=), :body => fixture('v1-user'))
+    user = Intercom::User.find(:email => "[email protected]")
+    FakeWeb.register_uri(:post, %r(/events), :status => ["202", "Created"])
+    user.log_event("signup").event_name.must_equal "signup"
+  end
 
   it "should failover to good endpoint when first one is un-reachable" do
     FakeWeb.allow_net_connect = %r(127.0.0.7)

spec/unit/intercom/user_event_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe "Intercom::UserEvent" do
+  
+  let (:user) {Intercom::User.new("email" => "[email protected]", :user_id => "12345", :created_at => Time.now, :name => "Jim Bob")}
+  let (:created_time) {Time.now - 300}
+  
+  it "creates a user event" do
+    Intercom.expects(:post).with("/events",
+                                 { :type => 'event.list',
+                                   :data => [ {:event_name => "signup", :created => created_time.to_i, :type => 'event', 
+                                      :user => { :user_id => user.user_id}, :metadata => {:some => "data"}
+                                    }]}).returns(:status => 200)
+
+    Intercom::UserEvent.create({ :event_name => "signup", :user => user, :created_at => created_time, :metadata => {:some => "data"} })
+  end
+
+  it 'automatically adds a created time upon creation' do
+    Intercom.expects(:post).with("/events",
+                                 { :type => 'event.list',
+                                   :data => [ {:event_name => "sale of item", :created => Time.now.to_i, :type => 'event', :user => { :user_id => user.user_id}
+                                    }]}).returns(:status => 200)
+    
+    Intercom::UserEvent.create({ :event_name => "sale of item", :user => user })
+  end
+  
+  it "creates a user event with metadata" do
+    Intercom.expects(:post).with("/events",
+                                 { :type => 'event.list',
+                                   :data => [ {:event_name => "signup", :created => created_time.to_i, :type => 'event', :user => { :user_id => user.user_id}, :metadata => { :something => "here"}
+                                    }]}).returns(:status => 200)
+    Intercom::UserEvent.create({ :event_name => "signup", :user => user, :created_at => created_time, :metadata => { :something => "here"} })
+  end
+
+  it 'fails when no user supplied' do
+    user_event = Intercom::UserEvent.new
+    user_event.event_name = "some event"
+    user_event.created_at = Time.now
+    proc { user_event.save }.must_raise ArgumentError, "Missing User"
+  end
+  
+  describe 'while batching events' do
+    
+    let (:event1) do
+      user_event = Intercom::UserEvent.new
+      user_event.event_name = "first event"
+      user_event.created_at = Time.now
+      user_event.user = user
+      user_event
+    end
+
+    let (:event2) do
+      user_event = Intercom::UserEvent.new
+      user_event.event_name = "second event"
+      user_event.created_at = Time.now
+      user_event
+    end
+    
+    it 'creates batched events' do
+      Intercom.expects(:post).with("/events",
+                                   { :type => 'event.list',
+                                     :data => [ 
+                                         {:event_name => "first event", :created => event1.created_at.to_i,
+                                          :type => 'event', :user => {:user_id => user.user_id}},
+                                         {:event_name => "second event", :created => event2.created_at.to_i,
+                                          :type => 'event'},
+                                     ],
+                                     :user => { :user_id => user.user_id}}).returns(:status => 200)
+      Intercom::UserEvent.save_batch_events([event1, event2], user)
+    end
+  end
+end

spec/unit/intercom/user_spec.rb

@@ -262,4 +262,13 @@
     first_company_as_hash["created_at"].must_equal time.to_i
     second_company_as_hash["created_at"].must_equal time.to_i
   end
+  
+  it "logs user events" do
+    user = Intercom::User.new("email" => "[email protected]", :user_id => "12345", :created_at => Time.now, :name => "Jim Bob")
+    Intercom::UserEvent.expects(:create).with(:event_name => 'registration', :user => user)
+    event = user.log_event('registration')
+    
+    Intercom::UserEvent.expects(:create).with(:event_name => 'another', :user => user, :created => 1391691571, :company_id => "6")
+    event = user.log_event("another", {:created => 1391691571, :company_id => "6"})
+  end
 end