Merge pull request #69 from intercom/penguin/add_support_for_events

Added support for Events

Author: theirishpenguin

README.md

@@ -82,6 +82,54 @@ Intercom::Impression.create(:email => "[email protected]", :location => "/path/in/
 Intercom::Note.create(:email => "[email protected]", :body => "This is the text of the note")
 ```
 
+#### Events
+The simplest way to create an event is directly on the user
+```ruby
+user = Intercom::User.find_by_email("[email protected]")
+user.track_event("invited-friend")
+```
+
+For more control create events through Intercom::Event
+```ruby
+Intercom::Event.create(:event_name => "invited-friend", :user => user)
+
+# With an explicit event creation date
+Intercom::Event.create(:event_name => "invited-friend", :user => user, :created_at => 1391691571)
+
+# With metadata
+Intercom::Event.create(:event_name => "invited-friend", :user => user,
+  metadata => { 
+    :invitee_email => '[email protected]',  
+    :invite_code => 'ADDAFRIEND'
+  }
+)
+```
+
+Metadata Objects support a few simple types that Intercom can present on your behalf 
+
+```ruby
+Intercom::Event.create(:event_name => "placed-order", :user => current_user,
+  metadata => { 
+    :order_date => Time.now.to_i,  
+    :stripe_invoice => 'inv_3434343434', 
+    :order_number => { 
+      :value => '3434-3434', 
+      :url => 'https://example.org/orders/3434-3434' 
+    },
+    price: { 
+      :currency => 'usd',  
+      :amount => 2999 
+    }    
+  }
+)
+```
+
+The metadata key values in the example are treated as follows-
+- order_date: a Date (key ends with '_date').
+- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
+- order_number: a Rich Link (value contains 'url' and 'value' keys)
+- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
+
 ### Errors
 ```ruby
 Intercom::AuthenticationError

changes.txt

@@ -1,3 +1,6 @@
+0.3.0
+- Renamed UserEvents to Events
+
 0.2.0
 - Add UserEvents.
 

intercom.gemspec

@@ -6,8 +6,8 @@ require "intercom/version"
 Gem::Specification.new do |spec|
   spec.name        = "intercom"
   spec.version     = Intercom::VERSION
-  spec.authors     = ["Ben McRedmond", "Ciaran Lee", "Darragh Curran", "Jeff Gardner", "Kyle Daigle"]
-  spec.email       = ["[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]"]
+  spec.authors     = ["Ben McRedmond", "Ciaran Lee", "Darragh Curran", "Jeff Gardner", "Kyle Daigle", "Declan McGrath", "Jamie Osler"]
+  spec.email       = ["[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]"]
   spec.homepage    = "https://www.intercom.io"
   spec.summary     = %q{Ruby bindings for the Intercom API}
   spec.description = %Q{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. }

lib/intercom.rb

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

lib/intercom/user_event.rb lib/intercom/event.rblib/intercom/user_event.rb renamed to lib/intercom/event.rb

@@ -5,46 +5,46 @@
 module Intercom
 
   ##
-  # Represents a User Event
+  # Represents an Event
   #
-  # A user event consists of an event_name and a user the event applies to. The user is identified via email or id.
+  # An 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_at => Time.now)
+  #  event = Intercom::Event.create(:event_name => "post", :user => current_user, :created_at => 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_at = Time.now
-  #  user_event.metadata = {
+  #  event = Intercom::Event.new
+  #  event.event_name = "publish-post"
+  #  event.user = current_user
+  #  event.created_at = Time.now
+  #  event.metadata = {
   #   :title => 'Gravity Review',
   #   :link => 'https://example.org/posts/22',
   #   :comments => 'https://example.org/posts/22/comments'
   # }
-  #  user_event.save
+  #  event.save
   #
   # == Batch
   #
-  # User events can be created in batches, and sent as one request. To do some, create user events
+  # Events can be created in batches, and sent as one request. To do some, create events
   # without calling .create, as follows:
   # 
-  # user_event = Intercom::UserEvent.new
-  # user_event.event_name = "publish-post"
-  # user_event.user = current_user
+  # event = Intercom::Event.new
+  # event.event_name = "publish-post"
+  # 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)
+  # Intercom::Event.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
+  class Event
     extend RequiresParameters
     include HashableObject
 
@@ -56,24 +56,24 @@ def initialize(attributes={})
     end
 
     ##
-    # Creates a new User Event using params and saves it
+    # Creates a new 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
+      Event.new(params).save
     end
 
     ##
-    # Save the User Event
+    # Save the Event
     def save
       raise ArgumentError.new("Missing User") if user.nil?
-      UserEvent.save_batch_events([self])
+      Event.save_batch_events([self])
       self
     end
 
     ##
-    # Save a list of User Events, with an optional base_user
+    # Save a list of Events, with an optional base_user
     def self.save_batch_events(events, base_user=nil)
       hash = { :type => 'event.list', :data => []}
       hash[:user] = user_hash(base_user) if base_user
@@ -92,7 +92,7 @@ def self.post_to_intercom(hash)
     end
 
     def user_hash
-      UserEvent.user_hash(user)
+      Event.user_hash(user)
     end
 
     def event_hash

lib/intercom/user.rb

@@ -337,13 +337,13 @@ def companies=(companies)
     end
 
     ##
-    # Creates a UserEvent for the given User
+    # Creates an Event for the given User
     # @param {Hash} options, keys for :created_at (Unix timestamp) and metadata
-    def log_event(event_name, options={})
+    def track_event(event_name, options={})
       attributes = {:event_name => event_name, :user => self}
       attributes[:created_at] = options[:created_at] unless options[:created_at].nil?
       attributes[:metadata] = options[:metadata] unless options[:metadata].nil?
-      UserEvent.create(attributes)
+      Event.create(attributes)
     end
 
     protected

lib/intercom/version.rb

@@ -1,3 +1,3 @@
 module Intercom #:nodoc:
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

spec/integration/intercom_api_integration_spec.rb

@@ -76,35 +76,35 @@ def fixture(name)
     note.user.email.must_equal "[email protected]"
   end
 
-  it "should create a user event" do
+  it "should create an 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"
+    Intercom::Event.create(:event_name => "signup", :created_at => 1391691571, :user => user).event_name.must_equal "signup"
   end
 
-  it "should create batch user events" do
+  it "should create batch 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 = Intercom::Event.new
     first_event.event_name = "first event"
     first_event.created_at = Time.now
     first_event.user = user
 
-    second_event = Intercom::UserEvent.new
+    second_event = Intercom::Event.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)
+    Intercom::Event.save_batch_events([first_event, second_event], user)
   end
 
-  it "should create a user event from a user" do
+  it "should create an 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"
+    user.track_event("signup").event_name.must_equal "signup"
   end
 
   it "should failover to good endpoint when first one is un-reachable" do
@@ -131,4 +131,4 @@ def fixture(name)
     proc { Intercom::User.find(:email => "[email protected]")}.must_raise Intercom::BadGatewayError
 
   end
-end
+end

spec/unit/intercom/user_event_spec.rb

@@ -1,18 +1,18 @@
 require 'spec_helper'
 
-describe "Intercom::UserEvent" do
+describe "Intercom::Event" 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
+  it "creates an 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},
                                     }]}).returns(:status => 200)
 
-    Intercom::UserEvent.create({ :event_name => "signup", :user => user, :created_at => created_time })
+    Intercom::Event.create({ :event_name => "signup", :user => user, :created_at => created_time })
   end
 
   it 'automatically adds a created time upon creation' do
@@ -21,22 +21,22 @@
                                    :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 })
+    Intercom::Event.create({ :event_name => "sale of item", :user => user })
   end
 
-  it "creates a user event with metadata" do
+  it "creates an 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"} })
+    Intercom::Event.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"
+    event = Intercom::Event.new
+    event.event_name = "some event"
+    event.created_at = Time.now
+    proc { event.save }.must_raise ArgumentError, "Missing User"
   end
 
   it 'uses the user.email if no user.id found' do
@@ -47,24 +47,24 @@
                                       :user => { :email => user2.email}
                                     }]}).returns(:status => 200)
 
-    Intercom::UserEvent.create({ :event_name => "signup", :user => user2, :created_at => created_time })
+    Intercom::Event.create({ :event_name => "signup", :user => user2, :created_at => created_time })
   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
+      event = Intercom::Event.new
+      event.event_name = "first event"
+      event.created_at = Time.now
+      event.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
+      event = Intercom::Event.new
+      event.event_name = "second event"
+      event.created_at = Time.now
+      event
     end
 
     it 'creates batched events' do
@@ -77,7 +77,7 @@
                                           :type => 'event'},
                                      ],
                                      :user => { :user_id => user.user_id}}).returns(:status => 200)
-      Intercom::UserEvent.save_batch_events([event1, event2], user)
+      Intercom::Event.save_batch_events([event1, event2], user)
     end
   end
 end

spec/unit/intercom/user_spec.rb

@@ -263,12 +263,12 @@
     second_company_as_hash["created_at"].must_equal time.to_i
   end
 
-  it "logs user events" do
+  it "tracks 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::Event.expects(:create).with(:event_name => 'registration', :user => user)
+    event = user.track_event('registration')
 
-    Intercom::UserEvent.expects(:create).with(:event_name => 'another', :user => user, :created_at => 1391691571)
-    event = user.log_event("another", {:created_at => 1391691571})
+    Intercom::Event.expects(:create).with(:event_name => 'another', :user => user, :created_at => 1391691571)
+    event = user.track_event("another", {:created_at => 1391691571})
   end
 end