adds support for timestamp

lib/heap/client.rb

@@ -106,7 +106,7 @@ def add_user_properties(identity, properties)
   #   each value must be a Number or String with fewer than 1024 characters
   # @return [HeapAPI::Client] self
   # @see https://heapanalytics.com/docs/server-side#track
-  def track(event, identity, properties = nil)
+  def track(event, identity, properties = nil, timestamp = nil)
     ensure_valid_app_id!
 
     event_name = event.to_s
@@ -118,6 +118,12 @@ def track(event, identity, properties = nil)
       :identity => identity.to_s,
       :event => event,
     }
+
+    unless timestamp.nil?
+      body[:timestamp] = timestamp
+      ensure_valid_timestamp! timestamp
+    end
+
     unless properties.nil?
       body[:properties] = properties
       ensure_valid_properties! properties

lib/heap/validations.rb

@@ -74,4 +74,19 @@ def ensure_valid_properties!(properties)
     end
   end
   private :ensure_valid_properties!
+
+  def ensure_valid_timestamp!(timestamp)
+    if timestamp.kind_of?(String)
+      Time.iso8601(timestamp)
+    elsif timestamp.kind_of?(Numeric)
+    else
+      raise ArgumentError,
+        "Unsupported timestamp format. Must be iso8601 or unix epoch " +
+        "milliseconds"
+    end
+  rescue ArgumentError
+    raise ArgumentError,
+      "Unsupported timestamp format. Must be iso8601 or unix epoch milliseconds"
+  end
+  private :ensure_valid_timestamp!
 end

test/client_track_test.rb

@@ -121,6 +121,18 @@ def test_track_with_array_property_value
         exception.message
   end
 
+  def test_track_with_datetime_timestamp
+    invalid_timestamp = DateTime.now
+
+    exception = assert_raises ArgumentError do
+      @heap.track 'test_track_with_datetime_timestamp', 'test-identity',
+          {}, invalid_timestamp
+    end
+    assert_equal ArgumentError, exception.class
+    assert_equal 'Unsupported timestamp format. Must be iso8601 or unix epoch' +
+    ' milliseconds', exception.message
+  end
+
   def test_track
     @stubs.post '/api/track' do |env|
       golden_body = {
@@ -174,6 +186,26 @@ def test_track_with_properties
         'test-identity','foo' => 'bar', :heap => :hurray)
   end
 
+  def test_track_with_timestamp
+    time = DateTime.now.iso8601
+    @stubs.post '/api/track' do |env|
+      golden_body = {
+        'app_id' => 'test-app-id',
+        'identity' => 'test-identity',
+        'event' => 'test_track_with_timestamp',
+        'timestamp' => time
+      }
+      assert_equal 'application/json', env[:request_headers]['Content-Type']
+      assert_equal @heap.user_agent, env[:request_headers]['User-Agent']
+      assert_equal golden_body, JSON.parse(env[:body])
+
+      [200, { 'Content-Type' => 'text/plain; encoding=utf8' }, '']
+    end
+
+    assert_equal @heap, @heap.track('test_track_with_timestamp',
+        'test-identity', nil, time)
+  end
+
   def test_track_error
     @stubs.post '/api/track' do |env|
       [400, { 'Content-Type' => 'text/plain; encoding=utf8' }, 'Bad request']