itly-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f956ac42d9761509feed18e020c4c5afee5cfa5928f099e1895b982e59dd5d10
+  data.tar.gz: e980e7b80fab1c12ce52ec928afbd264221a1d0ba9d1ba9570c69c849e9a42a9
+SHA512:
+  metadata.gz: 85ab4bfde5fc16accc2629d83417ca697dfbdd6511ad26b95bfdde8cdff39346f76034897ae028916d452ed1a37afe8a37e4a2a406cf19187dbfbfd9352cd20e
+  data.tar.gz: 5b90b6d14135f194aa63c1b3d0cd09119a11d1b84cae7b3f93d84455220a97c7236f51606250c7aadd2309aef085df334c6e1cfbd72e8d7dd9ac476b148a1777

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in itly-sdk.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'rbs', '~> 1.0'
+gem 'rspec'
+gem 'steep', '~> 0.41'

data/Steepfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature 'sig'
+
+  check 'lib'
+
+  library 'logger', 'set', 'itly-sdk'
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'itly-sdk'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Configure and load RBS
+unless ENV['DISABLE_TYPE_CHECKING']
+  ENV['RBS_TEST_TARGET'] = 'Itly::*, AcceptancePlugin, AcceptancePluginCallOptions, FakeCallOptions'
+  ENV['RBS_TEST_LOGLEVEL'] = 'warn'
+  ENV['RBS_TEST_DOUBLE_SUITE'] = 'rspec'
+  ENV['RBS_TEST_OPT'] = '-I./sig -I./spec/sig'
+
+  require 'rbs/test/setup'
+end
+
+# Start RSpec
+require 'rspec/core'
+
+ENV['RSPEC_RUN_FROM_SCRIPT'] = 'true'
+RSpec::Core::Runner.invoke

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/itly-sdk.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/itly/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'itly-sdk'
+  spec.version       = Itly::VERSION
+  spec.authors       = ['Iteratively', 'Benjamin Bouchet', 'Justin Fiedler', 'Andrey Sokolov']
+  spec.email         = ['support@iterative.ly']
+
+  spec.summary       = 'Iteratively SDK for Ruby'
+  spec.description   = 'Track and validate analytics with a unified, extensible interface ' \
+                       'that works with all your 3rd party analytics providers.'
+  spec.homepage      = 'https://github.com/iterativelyhq/itly-sdk-ruby'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/iterativelyhq/itly-sdk-ruby/sdk'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+end

data/lib/itly-sdk.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'itly/version'
+require_relative 'itly/options/environment'
+require_relative 'itly/options/validation'
+require_relative 'itly/exceptions'
+require_relative 'itly/validation_response'
+require_relative 'itly/plugin_call_options'
+require_relative 'itly/plugin_options'
+require_relative 'itly/plugins'
+require_relative 'itly/plugin'
+require_relative 'itly/options'
+require_relative 'itly/event'
+require_relative 'itly/itly'
+require_relative 'itly/loggers'

data/lib/itly/event.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # Event object used to communicate data between Itly core SDK and its plugins
+  #
+  # Properties:
+  # +name+: The event's name.
+  # +properties+: The event's properties.
+  # +id+: The event's unique ID in Iteratively.
+  # +version+: The event's version, e.g. 2.0.1.
+  # +plugins+: Granular Event Destinations: to control to which plugin to forward this event to
+  #
+  class Event
+    attr_reader :name, :properties, :id, :version, :plugins
+
+    ##
+    # Create a new Event object
+    #
+    # @param [String] name: The event's name.
+    # @param [Hash] properties: The event's properties.
+    # @param [String] id: The event's unique ID in Iteratively.
+    # @param [String] version: The event's version, e.g. 2.0.1.
+    # @param [Hash] plugins: Granular Event Destinations: to control to which plugin to forward this event to
+    #
+    def initialize(name:, properties: {}, id: nil, version: nil, plugins: {})
+      @name = name
+      @properties = properties
+      @id = id
+      @version = version
+      @plugins = plugins.transform_keys(&:to_s)
+    end
+
+    ##
+    # Describe the object
+    #
+    # @return [String] the object description
+    #
+    def to_s
+      str = "#<#{self.class.name}: name: #{name}, "
+      str += "id: #{id}, " unless id.nil?
+      str += "version: #{version}, " unless version.nil?
+      str + "properties: #{properties}>"
+    end
+
+    ##
+    # Compare the object to another
+    #
+    # @param [Object] other: the object to compare to
+    #
+    # @return [True/False] are the objects similar
+    #
+    def ==(other)
+      other.class == self.class && [name, properties, id, version] ==
+        [other.name, other.properties, other.id, other.version]
+    end
+  end
+end

data/lib/itly/exceptions.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Itly main class
+class Itly
+  class InitializationError < StandardError; end
+
+  class ValidationError < StandardError; end
+
+  class RemoteError < StandardError; end
+end

data/lib/itly/itly.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+##
+# Itly main class
+#
+class Itly
+  include Itly::Plugins
+
+  ##
+  # Create a new Itly object.
+  #
+  # The +is_initialized+ instance variable is a True/False flag indicating
+  # if the +load+ method was called on the object.
+  #
+  def initialize
+    @is_initialized = false
+  end
+
+  ##
+  # Load options ans the plugins. It must be called only once on an object.
+  #
+  # Accept an optional block to define the options. The variable yielded in
+  # the block is of type `Itly::Options`.
+  #
+  # Calls the +load+ method of each plugin passing the +options+ object as an argument.
+  #
+  # @param [Hash, nil] context: to assign to the "context" Event object. Default to nil
+  #
+  def load(context: nil)
+    # Ensure #load was not already called on this object
+    raise InitializationError, 'Itly is already initialized.' if @is_initialized
+
+    # Create a new Options object and yield it is a block is provided
+    @options = Itly::Options.new
+    yield @options if block_given?
+
+    # Create the context event
+    @context = context.nil? ? nil : Itly::Event.new(name: 'context', properties: context)
+
+    # Log
+    logger&.info 'load()'
+    logger&.info 'Itly is disabled!' unless enabled?
+    logger&.warn 'No plugin enabled!' if options.plugins.empty?
+
+    # pass options to plugins
+    run_on_plugins { |plugin| plugin.load options: options.for_plugin } if enabled?
+
+    # Mark that the #load method was called on this object
+    @is_initialized = true
+  end
+
+  ##
+  # Identify a user in your application and associate all future events with
+  # their identity, or to set their traits.
+  #
+  # Validates the +properties+ with all registered plugins first.
+  # Raises a Itly::ValidationError if one of the validations failed and
+  # if your set the +options.validation+ value to +ERROR_ON_INVALID+.
+  #
+  # Call +identify+ on all plugins and call +post_identify+ on all plugins.
+  #
+  # Example:
+  #
+  #     itly.identify user_id: 'MyUser123', role: 'admin'
+  #
+  # @param [String] user_id: the id of the user in your application
+  # @param [Hash] properties: the user's traits to pass to your application
+  # @param [Hash] options: plugin specific option. The keys must correspond
+  #   to a plugin id, and the values will be passed only to the plugin identified by the key.
+  #
+  def identify(user_id:, properties: {}, options: {})
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log user_id: user_id, properties: properties, options: options
+    logger&.info "identify(#{log})"
+
+    # Validate and run on all plugins
+    event = Event.new name: 'identify', properties: properties
+
+    action = ->(plugin, combined_event) {
+      plugin.identify(
+        user_id: user_id, properties: combined_event.properties, options: options[plugin.id]
+      )
+    }
+
+    post_action = ->(plugin, combined_event, validation_results) {
+      plugin.post_identify(
+        user_id: user_id, properties: combined_event.properties, validation_results: validation_results
+      )
+    }
+
+    validate_and_send_to_plugins event: event, action: action, post_action: post_action
+  end
+
+  ##
+  # Associate a user with their group (for example, their department or company),
+  # or to set the group's traits.
+  #
+  # Validates the +properties+ with all registered plugins first.
+  # Raises a Itly::ValidationError if one of the validations failed and
+  # if your set the +options.validation+ value to +ERROR_ON_INVALID+.
+  #
+  # Call +group+ on all plugins and call +post_group+ on all plugins.
+  #
+  # Example:
+  #
+  #     itly.group user_id: 'MyUser123', group_id: 'MyGroup456', name: 'Iteratively, Inc.'
+  #
+  # @param [String] user_id: the id of the user in your application
+  # @param [String] group_id: the id of the group in your application
+  # @param [Hash] properties: The list of properties to pass to your application
+  # @param [Hash] options: plugin specific option. The keys must correspond
+  #   to a plugin id, and the values will be passed only to the plugin identified by the key.
+  #
+  def group(user_id:, group_id:, properties: {}, options: {})
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log user_id: user_id, group_id: group_id, properties: properties, options: options
+    logger&.info "group(#{log})"
+
+    # Validate and run on all plugins
+    event = Event.new name: 'group', properties: properties
+
+    action = ->(plugin, combined_event) {
+      plugin.group(
+        user_id: user_id, group_id: group_id, properties: combined_event.properties,
+        options: options[plugin.id]
+      )
+    }
+
+    post_action = ->(plugin, combined_event, validation_results) {
+      plugin.post_group(
+        user_id: user_id, group_id: group_id, properties: combined_event.properties,
+        validation_results: validation_results
+      )
+    }
+
+    validate_and_send_to_plugins event: event, action: action, post_action: post_action
+  end
+
+  ##
+  # The Page method lets you record page views, along with optional extra information about
+  # the page viewed by the user.
+  #
+  # Validates the +properties+ with all registered plugins first.
+  # Raises a Itly::ValidationError if one of the validations failed and
+  # if your set the +options.validation+ value to +ERROR_ON_INVALID+.
+  #
+  # Call +page+ on all plugins and call +post_page+ on all plugins.
+  #
+  # Example:
+  #
+  #     itly.page user_id: 'MyUser123', category: 'Products', name: 'MyPage456', name: 'Iteratively, Inc.'
+  #
+  # @param [String] user_id: the id of the user in your application
+  # @param [String] category: the category of the page
+  # @param [String] name: the name of the page.
+  # @param [Hash] properties: The list of properties to pass to your application
+  # @param [Hash] options: plugin specific option. The keys must correspond
+  #   to a plugin id, and the values will be passed only to the plugin identified by the key.
+  #
+  def page(user_id:, category: nil, name: nil, properties: {}, options: {})
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log(
+      user_id: user_id, category: category, name: name, properties: properties, options: options
+    )
+    logger&.info "page(#{log})"
+
+    # Validate and run on all plugins
+    event = Event.new name: 'page', properties: properties
+
+    action = ->(plugin, combined_event) {
+      plugin.page(
+        user_id: user_id, category: category, name: name, properties: combined_event.properties,
+        options: options[plugin.id]
+      )
+    }
+
+    post_action = ->(plugin, combined_event, validation_results) {
+      plugin.post_page(
+        user_id: user_id, category: category, name: name, properties: combined_event.properties,
+        validation_results: validation_results
+      )
+    }
+
+    validate_and_send_to_plugins event: event, action: action, post_action: post_action
+  end
+
+  ##
+  # Track an event, call the event's corresponding function on plugins.
+  #
+  # Validates the +properties+ of the +Event+ object passed as parameter
+  # with all registered plugins first.
+  # Raises a Itly::ValidationError if one of the validations failed and
+  # if your set the +options.validation+ value to +ERROR_ON_INVALID+.
+  #
+  # The properties of the +context+ instance attribute passed when called #load
+  # are merged with the +event+ parameter before validation and calling the event
+  # on your application.
+  #
+  # Call +track+ on all plugins and call +post_track+ on all plugins.
+  #
+  # Example:
+  #
+  #     event = Itly::Event.new name: 'watched_video', properties: {'video_id' => 'MyVider123', watch_time: '123456'}
+  #     itly.track user_id: 'MyUser123', event: event
+  #
+  # @param [String] user_id: the id of the user in your application
+  # @param [Event] event: the Event object to pass to your application
+  # @param [Hash] options: plugin specific option. The keys must correspond
+  #   to a plugin id, and the values will be passed only to the plugin identified by the key.
+  #
+  def track(user_id:, event:, options: {})
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log(
+      user_id: user_id, event: event&.name, properties: event&.properties, options: options
+    )
+    logger&.info "track(#{log})"
+
+    # Validate and run on all plugins
+    action = ->(plugin, combined_event) {
+      plugin.track user_id: user_id, event: combined_event, options: options[plugin.id]
+    }
+
+    post_action = ->(plugin, combined_event, validation_results) {
+      plugin.post_track user_id: user_id, event: combined_event, validation_results: validation_results
+    }
+
+    validate_and_send_to_plugins event: event, context: @context, action: action, post_action: post_action
+  end
+
+  ##
+  # Associate one user ID with another (typically a known user ID with an anonymous one).
+  #
+  # Call +alias+ on all plugins and call +post_alias+ on all plugins.
+  #
+  # @param [String] user_id: The ID that the user will be identified by going forward. This is
+  #   typically the user's database ID (as opposed to an anonymous ID), or their updated ID
+  #   (for example, if the ID is an email address which the user just updated).
+  # @param [String] previous_id: The ID the user has been identified by so far.
+  # @param [Hash] options: plugin specific option. The keys must correspond
+  #   to a plugin id, and the values will be passed only to the plugin identified by the key.
+  #
+  def alias(user_id:, previous_id:, options: {})
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log user_id: user_id, previous_id: previous_id, options: options
+    logger&.info "alias(#{log})"
+
+    # Run on all plugins
+    run_on_plugins do |plugin|
+      plugin.alias user_id: user_id, previous_id: previous_id, options: options[plugin.id]
+    end
+    run_on_plugins do |plugin|
+      plugin.post_alias user_id: user_id, previous_id: previous_id
+    end
+  end
+
+  ##
+  # Send +flush+ to your plugins.
+  #
+  # Call +flush+ on all plugins.
+  #
+  def flush
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    logger&.info 'flush()'
+
+    # Run on all plugins
+    run_on_plugins(&:flush)
+  end
+
+  ##
+  # Send +shutdown+ to your plugins.
+  #
+  # Call +shutdown+ on all plugins.
+  #
+  def shutdown
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    logger&.info 'shutdown()'
+
+    # Run on all plugins
+    run_on_plugins(&:shutdown)
+  end
+
+  ##
+  # Reset the SDK's (and all plugins') state. This method is usually called when a user logs out.
+  #
+  # Call +reset+ on all plugins.
+  #
+  def reset
+    # Run only if the object is enabled and was initialized
+    return unless was_initialized? && enabled?
+
+    # Log
+    logger&.info 'reset()'
+
+    # Run on all plugins
+    run_on_plugins(&:reset)
+  end
+
+  ##
+  # Validate an Event
+  #
+  # Call +event+ on all plugins and collect their return values.
+  #
+  # @param [Event] event: the event to validate
+  #
+  # @return [Array] array of Itly::ValidationResponse objects that were generated by the plugins
+  #
+  def validate(event:)
+    return unless was_initialized? && validation_enabled?
+
+    # Log
+    log = Itly::Loggers.vars_to_log event: event
+    logger&.info "validate(#{log})"
+
+    # Run on all plugins
+    run_on_plugins { |plugin| plugin.validate event: event }
+  end
+
+  def is_loaded?
+    !!@is_initialized
+  end
+
+  private
+
+  def was_initialized?
+    @is_initialized ? true : raise(InitializationError, 'Itly is not initialized. Call #load { |options| ... }')
+  end
+
+  def validate_and_send_to_plugins(action:, post_action:, event:, context: nil)
+    # Perform validation on the context and the event
+    context_validations, event_validations, is_valid = validate_context_and_event context, event
+    validations = context_validations + event_validations
+
+    # Call the action on all plugins
+    event.properties.merge! context.properties if context
+
+    if is_valid || @options.validation == Itly::Options::Validation::TRACK_INVALID
+      run_on_plugins do |plugin|
+        action.call(plugin, event) unless event.plugins[plugin.id].is_a?(FalseClass)
+      end
+    end
+
+    # Log all errors
+    log_validation_errors validations, event
+
+    # Call the post_action on all plugins
+    run_on_plugins do |plugin|
+      post_action.call(plugin, event, validations) unless event.plugins[plugin.id].is_a?(FalseClass)
+    end
+
+    # Throw an exception if requested
+    raise_validation_errors is_valid, validations, event
+  end
+
+  def validate_context_and_event(context, event)
+    # Validate the context
+    context_validations = (validate event: context if context) || []
+
+    # Validate the event
+    event_validations = validate(event: event) || []
+
+    # Check if all validation succeeded
+    is_valid = (context_validations + event_validations).all?(&:valid)
+
+    [context_validations, event_validations, is_valid]
+  end
+
+  def log_validation_errors(validations, event)
+    validations.reject(&:valid).each do |response|
+      @options.logger&.error %(Validation error for "#{event.name}" )\
+        "in #{response.plugin_id}. Message: #{response.message}"
+    end
+  end
+
+  def raise_validation_errors(is_valid, validations, event)
+    return unless !is_valid && @options.validation == Itly::Options::Validation::ERROR_ON_INVALID
+
+    messages = validations.reject(&:valid).collect(&:message)
+    messages = messages.select { |m| !m.nil? && m.length.positive? }
+    messages << "Unknown error validating #{event.name}" if messages.empty?
+
+    raise ValidationError, messages.join('. ')
+  end
+end