amplitude-api 0.1.0 → 0.3.0

data/lib/amplitude_api/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class AmplitudeAPI
-  VERSION = '0.1.0'.freeze
+  VERSION = "0.3.0"
 end

data/lib/amplitude_api.rb

@@ -1,18 +1,20 @@
-require 'json'
-require 'typhoeus'
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
 
 # AmplitudeAPI
 class AmplitudeAPI
-  require_relative 'amplitude_api/config'
-  require_relative 'amplitude_api/event'
-  require_relative 'amplitude_api/identification'
+  require_relative "amplitude_api/config"
+  require_relative "amplitude_api/event"
+  require_relative "amplitude_api/identification"
 
-  TRACK_URI_STRING        = 'https://api.amplitude.com/httpapi'.freeze
-  IDENTIFY_URI_STRING     = 'https://api.amplitude.com/identify'.freeze
-  SEGMENTATION_URI_STRING = 'https://amplitude.com/api/2/events/segmentation'.freeze
-  DELETION_URI_STRING     = 'https://amplitude.com/api/2/deletions/users'.freeze
+  TRACK_URI_STRING        = "https://api.amplitude.com/2/httpapi"
+  IDENTIFY_URI_STRING     = "https://api.amplitude.com/identify"
+  SEGMENTATION_URI_STRING = "https://amplitude.com/api/2/events/segmentation"
+  DELETION_URI_STRING     = "https://amplitude.com/api/2/deletions/users"
 
-  USER_WITH_NO_ACCOUNT = "user who doesn't have an account".freeze
+  USER_WITH_NO_ACCOUNT = "user who doesn't have an account"
 
   class << self
     def config
@@ -38,12 +40,12 @@ class AmplitudeAPI
     # @param [ String ] event_name a string that describes the event, e.g. "clicked on Home"
     # @param [ String ] user a string or integer that uniquely identifies a user.
     # @param [ String ] device a string that uniquely identifies the device.
-    # @param [ Hash ] event_properties a hash that is serialized to JSON,
+    # @option options [ Hash ] event_properties a hash that is serialized to JSON,
     # and can contain any other property to be stored on the Event
-    # @param [ Hash ] user_properties a hash that is serialized to JSON,
+    # @option options [ Hash ] user_properties a hash that is serialized to JSON,
     # and contains user properties to be associated with the user
     #
-    # @return [ Typhoeus::Response ]
+    # @return [ Faraday::Response ]
     def send_event(event_name, user, device, options = {})
       event = AmplitudeAPI::Event.new(
         user_id: user,
@@ -68,10 +70,10 @@ class AmplitudeAPI
     def track_body(*events)
       event_body = events.flatten.map(&:to_hash)
 
-      {
+      JSON.generate(
         api_key: api_key,
-        event: JSON.generate(event_body)
-      }
+        events: event_body
+      )
     end
 
     # @overload track(event)
@@ -80,11 +82,11 @@ class AmplitudeAPI
     # @overload track([events])
     #   @param [ Array<AmplitudeAPI::Event> ] Send an array of events in a single request to Amplitude
     #
-    # @return [ Typhoeus::Response ]
+    # @return [ Faraday::Response ]
     #
     # Send one or more Events to the Amplitude API
     def track(*events)
-      Typhoeus.post(TRACK_URI_STRING, body: track_body(events))
+      Faraday.post(TRACK_URI_STRING, track_body(events), "Content-Type" => "application/json")
     end
 
     # ==== Identification related methods
@@ -123,40 +125,40 @@ class AmplitudeAPI
     # @overload identify([identifications])
     #   @param [ Array<AmplitudeAPI::Identify> ] Send an array of identifications in a single request to Amplitude
     #
-    # @return [ Typhoeus::Response ]
+    # @return [ Faraday::Response ]
     #
     # Send one or more Identifications to the Amplitude Identify API
     def identify(*identifications)
-      Typhoeus.post(IDENTIFY_URI_STRING, body: identify_body(identifications))
+      Faraday.post(IDENTIFY_URI_STRING, identify_body(identifications))
     end
 
     # ==== Event Segmentation related methods
 
     # Get metrics for an event with segmentation.
     #
-    # @param [ Hash ] e a hash that defines event.
+    # @param [ Hash ] event a hash that defines event.
     # @param [ Time ] start_time a start time.
     # @param [ Time ] end_time a end time.
-    # @param [ String ] m a string that defines aggregate function.
+    # @option options [ String ] m a string that defines aggregate function.
     # For non-property metrics: "uniques", "totals", "pct_dau", or "average" (default: "uniques").
     # For property metrics: "histogram", "sums", or "value_avg"
     # (note: a valid "group_by" value is required in parameter e).
-    # @param [ Integer ] i an integer that defines segmentation interval.
+    # @option options [ Integer ] i an integer that defines segmentation interval.
     # Set to -300000, -3600000, 1, 7, or 30 for realtime, hourly, daily, weekly,
     # and monthly counts, respectively (default: 1). Realtime segmentation is capped at 2 days,
     # hourly segmentation is capped at 7 days, and daily at 365 days.
-    # @param [ Array ] s an array that defines segment definitions.
-    # @param [ String ] g a string that defines property to group by.
-    # @param [ Integer ] limit an integer that defines number of Group By values
+    # @option options [ Array ] s an array that defines segment definitions.
+    # @option options [ String ] g a string that defines property to group by.
+    # @option options [ Integer ] limit an integer that defines number of Group By values
     # returned (default: 100). The maximum limit is 1000.
     #
-    # @return [ Typhoeus::Response ]
+    # @return [ Faraday::Response ]
     def segmentation(event, start_time, end_time, **options)
-      Typhoeus.get SEGMENTATION_URI_STRING, userpwd: "#{api_key}:#{secret_key}", params: {
+      Faraday.get SEGMENTATION_URI_STRING, userpwd: "#{api_key}:#{secret_key}", params: {
         e: event.to_json,
         m: options[:m],
-        start: start_time.strftime('%Y%m%d'),
-        end: end_time.strftime('%Y%m%d'),
+        start: start_time.strftime("%Y%m%d"),
+        end: end_time.strftime("%Y%m%d"),
         i: options[:i],
         s: (options[:s] || []).map(&:to_json),
         g: options[:g],
@@ -164,27 +166,48 @@ class AmplitudeAPI
       }.delete_if { |_, value| value.nil? }
     end
 
-    # ==== GDPR compliance methods
-
-    # Delete a user from amplitude when they request it to comply with GDPR
+    # Delete a user from amplitude
+    #
     # You must pass in either an array of user_ids or an array of amplitude_ids
     #
-    # @param [ user_ids ] (optional) the user_ids to delete
+    # @param [ Array<String> ] (optional) the user_ids to delete
     # based on your database
-    # @param [ amplitude_ids ] (optional) the amplitude_ids to delete
+    # @param [ Array<Integer> ] (optional) the amplitude_ids to delete
     # based on the amplitude database
-    # @param [ requester ] the email address of the person who
+    # @param [ String ] requester the email address of the person who
     # is requesting the deletion, optional but useful for reporting
-    #
-    # @return [ Typhoeus::Response ]
-    def delete(user_ids: nil, amplitude_ids: nil, requester: nil)
-      Typhoeus.post DELETION_URI_STRING,
-                    userpwd: "#{api_key}:#{config.secret_key}",
-                    body: {
-                      amplitude_ids: amplitude_ids,
-                      user_ids: user_ids,
-                      requester: requester
-                    }.delete_if { |_, value| value.nil? }
+    # @param [ Boolean ] (optional) ignore any invalid user IDs(users that do no
+    # exist in the project) that were passed in
+    # @param [ Boolean ] (optional) delete from the entire org rather than just
+    # this project.
+    # @return [ Faraday::Response ]
+    def delete(user_ids: nil, amplitude_ids: nil, requester: nil, ignore_invalid_id: nil, delete_from_org: nil)
+      user_ids = Array(user_ids)
+      amplitude_ids = Array(amplitude_ids)
+
+      faraday = Faraday.new do |conn|
+        conn.basic_auth config.api_key, config.secret_key
+      end
+
+      faraday.post(
+        DELETION_URI_STRING,
+        delete_body(user_ids, amplitude_ids, requester, ignore_invalid_id, delete_from_org),
+        "Content-Type" => "application/json"
+      )
+    end
+
+    private
+
+    def delete_body(user_ids, amplitude_ids, requester, ignore_invalid_id, delete_from_org)
+      body = {
+        amplitude_ids: amplitude_ids,
+        user_ids: user_ids,
+        requester: requester
+      }.delete_if { |_, value| value.nil? || value.empty? }
+
+      body[:ignore_invalid_id] = ignore_invalid_id.to_s if ignore_invalid_id
+      body[:delete_from_org] = delete_from_org.to_s if delete_from_org
+      JSON.generate(body)
     end
   end
 end

data/readme.md

@@ -19,7 +19,7 @@ AmplitudeAPI.config.api_key = "abcdef123456"
 
 
 event = AmplitudeAPI::Event.new({
-  user_id: "123",
+  user_id: "12345",
   event_type: "clicked on home",
   time: Time.now,
   insert_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
@@ -31,7 +31,7 @@ event = AmplitudeAPI::Event.new({
 AmplitudeAPI.track(event)
 ```
 
-## GDPR Compliance
+## User Privacy APIs
 
 The following code snippet will delete a user from amplitude
 
@@ -42,12 +42,13 @@ AmplitudeAPI.config.api_key = "abcdef123456"
 # Configure your Amplitude Secret Key
 AmplitudeAPI.config.secret_key = "secretMcSecret"
 
-AmplitudeAPI.delete(user_ids: [233],
-  requester: "privacy@mycompany.com"
+AmplitudeAPI.delete(user_ids: ["12345"],
+  requester: "privacy@example.com"
 )
 ```
 
-Currently, we are using this in Rails and using ActiveJob to dispatch events asynchronously. I plan on moving background/asynchronous support into this gem.
+Currently, we are using this in Rails and using ActiveJob to dispatch events asynchronously. I plan on moving
+background/asynchronous support into this gem.
 
 ## What's Next
 
@@ -55,7 +56,7 @@ Currently, we are using this in Rails and using ActiveJob to dispatch events asy
 * Configurable default account to use when no `user_id` present
 
 ## Other useful resources
-* [Amplitude HTTP Api Documentation](https://amplitude.zendesk.com/hc/en-us/articles/204771828)
+* [Amplitude HTTP API V2 Api Documentation](https://developers.amplitude.com/docs/http-api-v2)
 * [Segment.io Amplitude integration](https://segment.com/docs/integrations/amplitude/)
 
 ## Contributing

data/spec/lib/amplitude_api/event_spec.rb

@@ -1,277 +1,318 @@
-require 'spec_helper'
+# frozen_string_literal: true
+
+require "spec_helper"
 
 describe AmplitudeAPI::Event do
   user = Struct.new(:id)
 
-  context 'with a user object' do
-    describe '#body' do
+  context "with a user object" do
+    describe "#body" do
       it "populates with the user's id" do
         event = described_class.new(
           user_id: user.new(123),
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(123)
       end
     end
   end
 
-  context 'with a user id' do
-    describe '#body' do
+  context "with a user id" do
+    describe "#body" do
       it "populates with the user's id" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(123)
       end
     end
   end
 
-  context 'without a user' do
-    describe '#body' do
-      it 'populates with the unknown user' do
+  context "without a user" do
+    describe "#body" do
+      it "populates with the unknown user" do
         event = described_class.new(
           user_id: nil,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(AmplitudeAPI::USER_WITH_NO_ACCOUNT)
       end
     end
   end
 
-  describe 'init' do
-    context 'attributes' do
-      it 'accepts string attributes' do
+  describe "init" do
+    context "attributes" do
+      it "accepts string attributes" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
-          'user_id' => 123,
-          'device_id' => 'abcd',
-          'event_type' => 'sausage',
-          'event_properties' => { 'a' => 'b' },
-          'user_properties' => { 'c' => 'd' },
-          'time' => time,
-          'ip' => '127.0.0.1',
-          'platform' => 'Web',
-          'country' => 'United States',
-          'insert_id' => 'bestId'
+          "user_id" => 123,
+          "device_id" => "abcd",
+          "event_type" => "sausage",
+          "event_properties" => { "a" => "b" },
+          "user_properties" => { "c" => "d" },
+          "time" => time,
+          "ip" => "127.0.0.1",
+          "platform" => "Web",
+          "country" => "United States",
+          "insert_id" => "bestId"
         )
 
-        expect(event.to_hash).to eq(event_type: 'sausage',
+        expect(event.to_hash).to eq(event_type: "sausage",
                                     user_id: 123,
-                                    device_id: 'abcd',
-                                    event_properties: { 'a' => 'b' },
-                                    user_properties: { 'c' => 'd' },
+                                    device_id: "abcd",
+                                    event_properties: { "a" => "b" },
+                                    user_properties: { "c" => "d" },
                                     time: 1_451_606_400_000,
-                                    ip: '127.0.0.1',
-                                    platform: 'Web',
-                                    country: 'United States',
-                                    insert_id: 'bestId')
+                                    ip: "127.0.0.1",
+                                    platform: "Web",
+                                    country: "United States",
+                                    insert_id: "bestId")
       end
 
-      it 'accepts symbol attributes' do
+      it "accepts symbol attributes" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
           user_id: 123,
-          device_id: 'abcd',
-          event_type: 'sausage',
-          event_properties: { 'a' => 'b' },
-          user_properties: { 'c' => 'd' },
+          device_id: "abcd",
+          event_type: "sausage",
+          event_properties: { "a" => "b" },
+          user_properties: { "c" => "d" },
           time: time,
-          ip: '127.0.0.1',
-          platform: 'Web',
-          country: 'United States',
-          insert_id: 'bestId'
+          ip: "127.0.0.1",
+          platform: "Web",
+          country: "United States",
+          insert_id: "bestId"
         )
 
-        expect(event.to_hash).to eq(event_type: 'sausage',
+        expect(event.to_hash).to eq(event_type: "sausage",
                                     user_id: 123,
-                                    device_id: 'abcd',
-                                    event_properties: { 'a' => 'b' },
-                                    user_properties: { 'c' => 'd' },
+                                    device_id: "abcd",
+                                    event_properties: { "a" => "b" },
+                                    user_properties: { "c" => "d" },
                                     time: 1_451_606_400_000,
-                                    ip: '127.0.0.1',
-                                    platform: 'Web',
-                                    country: 'United States',
-                                    insert_id: 'bestId')
+                                    ip: "127.0.0.1",
+                                    platform: "Web",
+                                    country: "United States",
+                                    insert_id: "bestId")
       end
     end
 
-    context 'the user does not send in a price' do
-      it 'raises an error if the user sends in a product_id' do
+    context "the user sends a revenue_type or a product_id" do
+      it "raises an error if there is not a price neither a revenue" do
         expect do
           described_class.new(
             user_id: 123,
-            event_type: 'bad event',
-            product_id: 'hopscotch.4lyfe'
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe"
           )
-        end.to raise_error(ArgumentError)
+        end.to raise_error ArgumentError, /You must provide a price or a revenue/
+
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            revenue_type: "whatever"
+          )
+        end.to raise_error ArgumentError, /You must provide a price or a revenue/
       end
 
-      it 'raises an error if the user sends in a revenue_type' do
+      it "does not raise an error if there is a price" do
         expect do
           described_class.new(
             user_id: 123,
-            event_type: 'bad event',
-            revenue_type: 'tax return'
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe",
+            price: 10.2
           )
-        end.to raise_error(ArgumentError)
+        end.not_to raise_error
+
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            revenue_type: "whatever",
+            price: 10.2
+          )
+        end.not_to raise_error
+      end
+
+      it "does not raise an error if there is a revenue" do
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe",
+            revenue: 100.1
+          )
+        end.not_to raise_error
+
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            revenue_type: "whatever",
+            revenue: 100.1
+          )
+        end.not_to raise_error
       end
     end
   end
 
-  describe '#to_hash' do
-    it 'includes the event type' do
+  describe "#to_hash" do
+    it "includes the event type" do
       event = described_class.new(
         user_id: 123,
-        event_type: 'clicked on home'
+        event_type: "clicked on home"
       )
-      expect(event.to_hash[:event_type]).to eq('clicked on home')
+      expect(event.to_hash[:event_type]).to eq("clicked on home")
     end
 
-    it 'includes arbitrary properties' do
+    it "includes arbitrary properties" do
       event = described_class.new(
         user_id: 123,
-        event_type: 'clicked on home',
+        event_type: "clicked on home",
         event_properties: { abc: :def }
       )
       expect(event.to_hash[:event_properties]).to eq(abc: :def)
     end
 
-    describe 'time' do
-      it 'includes a time for the event' do
+    describe "time" do
+      it "includes a time for the event" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           time: time
         )
         expect(event.to_hash[:time]).to eq(1_451_606_400_000)
       end
 
-      it 'does not include time if it is not set' do
+      it "does not include time if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:time)
       end
     end
 
-    describe 'insert_id' do
-      it 'includes an insert_id for the event' do
+    describe "insert_id" do
+      it "includes an insert_id for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          insert_id: 'foo-bar'
+          event_type: "clicked on home",
+          insert_id: "foo-bar"
         )
-        expect(event.to_hash[:insert_id]).to eq('foo-bar')
+        expect(event.to_hash[:insert_id]).to eq("foo-bar")
       end
 
-      it 'does not include insert_id if it is not set' do
+      it "does not include insert_id if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:insert_id)
       end
     end
 
-    describe 'platform' do
-      it 'includes the platform for the event' do
+    describe "platform" do
+      it "includes the platform for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          platform: 'Web'
+          event_type: "clicked on home",
+          platform: "Web"
         )
-        expect(event.to_hash[:platform]).to eq('Web')
+        expect(event.to_hash[:platform]).to eq("Web")
       end
 
-      it 'does not include the platform if it is not set' do
+      it "does not include the platform if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:platform)
       end
     end
 
-    describe 'country' do
-      it 'includes the country for the event' do
+    describe "country" do
+      it "includes the country for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          country: 'United States'
+          event_type: "clicked on home",
+          country: "United States"
         )
-        expect(event.to_hash[:country]).to eq('United States')
+        expect(event.to_hash[:country]).to eq("United States")
       end
 
-      it 'does not include the country if it is not set' do
+      it "does not include the country if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:country)
       end
     end
 
-    describe 'revenue params' do
-      it 'includes the price if it is set' do
+    describe "revenue params" do
+      it "includes the price if it is set" do
         price = 100_000.99
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: price
         )
         expect(event.to_hash[:price]).to eq(price)
       end
 
-      it 'sets the quantity to 1 if the price is set and the quantity is not' do
-        price = 100_000.99
+      it "includes the quantity if it is set" do
+        quantity = 100
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          price: price
+          event_type: "clicked on home",
+          quantity: quantity,
+          price: 10.99
         )
-        expect(event.to_hash[:quantity]).to eq(1)
+        expect(event.to_hash[:quantity]).to eq(quantity)
       end
 
-      it 'includes the quantity if it is set' do
-        quantity = 100
+      it "includes the revenue if it is set" do
+        revenue = 100
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          quantity: quantity,
-          price: 10.99
+          event_type: "clicked on home",
+          quantity: 456,
+          revenue: revenue
         )
-        expect(event.to_hash[:quantity]).to eq(quantity)
+        expect(event.to_hash[:revenue]).to eq(revenue)
       end
 
-      it 'includes the productID if set' do
-        product_id = 'hopscotch.subscriptions.rule'
+      it "includes the productID if set" do
+        product_id = "hopscotch.subscriptions.rule"
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: 199.99,
           product_id: product_id
         )
         expect(event.to_hash[:productId]).to eq(product_id)
       end
 
-      it 'includes the revenueType if set' do
-        revenue_type = 'income'
+      it "includes the revenueType if set" do
+        revenue_type = "income"
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: 199.99,
           revenue_type: revenue_type
         )
         expect(event.to_hash[:revenueType]).to eq(revenue_type)
       end
 
-      it 'does not include revenue params if they are not set' do
+      it "does not include revenue params if they are not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:quantity)
         expect(event.to_hash).not_to have_key(:revenueType)
@@ -280,4 +321,44 @@ describe AmplitudeAPI::Event do
       end
     end
   end
+
+  describe "arbitrary properties" do
+    # We need to create a class for each test because the methods we are calling
+    # in this test group are modifying the class
+    let(:klass) { Class.new described_class }
+
+    let(:event) {
+      klass.new(
+        user_id: 123,
+        event_type: "bad event"
+      )
+    }
+
+    it "creates arbitrary properties when assigning values" do
+      event.arbitrary_property = "arbitrary value"
+
+      expect(event.arbitrary_property).to eq "arbitrary value"
+    end
+
+    it "responds_to? arbitrary properties" do
+      event.arbitrary_property = "arbitrary value"
+
+      expect(event.respond_to?(:arbitrary_property)).to be true
+      expect(event.respond_to?(:arbitrary_property=)).to be true
+    end
+
+    it "do not accepts blocks when assigning values to create properties" do
+      expect do
+        event.arbitrary_property { puts "whatever" }
+      end.to raise_error NoMethodError
+    end
+
+    it "includes arbitrary properties in the generated hash" do
+      event.arbitrary_property = "arbitrary value"
+
+      hash = event.to_hash
+
+      expect(hash).to include(arbitrary_property: "arbitrary value")
+    end
+  end
 end