itly-sdk 0.1.0

data/lib/itly/loggers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # Loggers class, provide default usual loggers for convenience
+  #
+  class Loggers
+    ##
+    # Logger to log into 'itly.log' file on the current directory
+    #
+    # @return [Logger] the logger
+    #
+    def self.itly_dot_log
+      Logger.new 'itly.log'
+    end
+
+    ##
+    # Logger to log to standard out
+    #
+    # @return [Logger] the logger
+    #
+    def self.std_out
+      Logger.new $stdout
+    end
+
+    ##
+    # No logger
+    #
+    # @return [NilClass] nothing
+    #
+    def self.nil_logger
+      nil
+    end
+
+    ##
+    # Shorthand to filter variables in a log message
+    #
+    # Check if the variable has a value, and return a list for the log message
+    #
+    # @param [Hash] vars: list of variables
+    # @return [String] log message
+    #
+    def self.vars_to_log(vars)
+      vars.collect do |name, value|
+        next if value.nil?
+
+        if value.is_a?(Hash) || value.is_a?(Array)
+          "#{name}: #{value}" if value.any?
+        else
+          "#{name}: #{value}"
+        end
+      end.compact.join ', '
+    end
+  end
+end

data/lib/itly/options.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# Itly main class
+class Itly
+  attr_reader :options
+
+  ##
+  # Options class for Itly object initialization
+  #
+  # Properties:
+  #
+  # +disabled+: A True/False specifying whether the Itly SDK does any work.
+  #   When true, all calls to the Itly SDK will be no-ops. Useful in local or development environments.
+  #
+  #   Defaults to false.
+  #
+  # +environment+: A Symbol specifying the environment the Itly SDK is running in.
+  #   Can be +Itly::Options::Environment::DEVELOPMENT+ or +Itly::Options::Environment::PRODUCTION+
+  #
+  #   Environment determines which Access Token is used to load the underlying analytics provider libraries.
+  #   The option also determines safe defaults for handling event validation errors. In production,
+  #   when the SDK detects an invalid event, it will log an error but still let the event through.
+  #   In development, the SDK will throw an exception to alert you that something is wrong.
+  #
+  #   Defaults to +DEVELOPMENT+.
+  #
+  # +plugins+: Pass the list of Plugins object that will receive all events to be tracked.
+  #
+  #   Example:
+  #     my_plugin = MyPlugin.new api_key: 'abc123'
+  #     itly = Itly.new
+  #     itly.load do |options|
+  #       options.plugins = [my_plugin]
+  #     end
+  #
+  # +validation+: Configures the Itly SDK's behavior when events or traits fail validation.
+  #   Value can be one of the following:
+  #   - +Itly::Options::Validation::DISABLED+: Disables validation altogether.
+  #   - +Itly::Options::Validation::TRACK_INVALID+: Specifies whether events that failed validation
+  #     should still be tracked. Defaults to false in development, true in production.
+  #   - +Itly::Options::Validation::ERROR_ON_INVALID+: Specifies whether the SDK should throw
+  #      an exception when validation fails. Defaults to true in development, false in production.
+  #
+  #   Defaults to +ERROR_ON_INVALID+ if the environment is set to +DEVELOPMENT+, or +TRACK_INVALID+
+  #   if the environment is set to +PRODUCTION+.
+  #
+  # +logger+: Allow to set a custom Logger. Must be a object of the Logger class or child class, and can be nil.
+  #   Deflault to nil, to disable Logging.
+  #
+  class Options
+    attr_accessor :disabled, :logger, :plugins, :environment
+    attr_writer :validation
+
+    ##
+    # Create a new Options object with default values
+    #
+    def initialize(
+      environment: Itly::Options::Environment::DEVELOPMENT,
+      disabled: false,
+      plugins: [],
+      validation: nil,
+      logger: nil
+    )
+      @environment = environment
+      @disabled = disabled
+      @plugins = plugins
+      @validation = validation
+      @logger = logger
+    end
+
+    ##
+    # Returns the options that are passed to plugin #load
+    #
+    # @return [Itly::PluginOptions] plugin options object
+    #
+    def for_plugin
+      ::Itly::PluginOptions.new environment: environment, logger: logger
+    end
+
+    ##
+    # Return the current validation behavior
+    #
+    # @return [Itly::Options::Validation] validation behavior
+    #
+    def validation
+      if @validation.nil?
+        if development?
+          Itly::Options::Validation::ERROR_ON_INVALID
+        else
+          Itly::Options::Validation::TRACK_INVALID
+        end
+      else
+        @validation
+      end
+    end
+  end
+
+  # Shortcut methods
+  private
+
+  def enabled?
+    !options.disabled
+  end
+
+  def validation_enabled?
+    options.validation != Itly::Options::Validation::DISABLED
+  end
+
+  def logger
+    options.logger
+  end
+end

data/lib/itly/options/environment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # Options class for Itly object initialization
+  #
+  class Options
+    ##
+    # This module contains values for the field +environment+ of the +Option+ object
+    #
+    module Environment
+      DEVELOPMENT = :development
+      PRODUCTION = :production
+    end
+
+    def development?
+      @environment == Itly::Options::Environment::DEVELOPMENT
+    end
+
+    def production?
+      @environment == Itly::Options::Environment::PRODUCTION
+    end
+  end
+end

data/lib/itly/options/validation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # Options class for Itly object initialization
+  #
+  class Options
+    ##
+    # This module contains values for the field +validation+ of the +Option+ object
+    #
+    module Validation
+      DISABLED = 0
+      TRACK_INVALID = 1
+      ERROR_ON_INVALID = 2
+    end
+  end
+end

data/lib/itly/plugin.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Itly main class
+class Itly
+  ##
+  # Parent class for all plugins
+  #
+  # When creating a custom plugin, you need to create a child class of Itly::Plugin
+  #
+  class Plugin
+    ##
+    # Called when the Itly SDK is being loaded and is ready to load your plugin.
+    #
+    # @param [Itly::PluginOptions] options: The option for the plugin
+    #
+    def load(options:); end
+
+    ##
+    # Identify a user in your application and associate all future events with
+    # their identity, or to set their traits.
+    #
+    # @param [String] user_id: the id of the user in your application
+    # @param [Hash] properties: the properties containing user's traits to pass to your application
+    # @param [Itly::PluginCallOptions] options: plugin specific options.
+    #
+    def identify(user_id:, properties: nil, options: nil); end
+
+    def post_identify(user_id:, properties:, validation_results:); end
+
+    ##
+    # Associate a user with their group (for example, their department or company),
+    # or to set the group's traits.
+    #
+    # @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 properties to pass to your application
+    # @param [Itly::PluginCallOptions] options: plugin specific option.
+    #
+    def group(user_id:, group_id:, properties: nil, options: nil); end
+
+    def post_group(user_id:, group_id:, properties:, validation_results:); end
+
+    ##
+    # Let record page views, along with optional extra information about the page viewed by the user.
+    #
+    # @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 properties to pass to your application
+    # @param [Itly::PluginCallOptions] options: plugin specific option.
+    #
+    def page(user_id:, category: nil, name: nil, properties: nil, options: nil); end
+
+    def post_page(user_id:, category:, name:, properties:, validation_results:); end
+
+    ##
+    # Track an event, call the event's corresponding function.
+    #
+    # See +Itly#track+ for more information
+    #
+    # @param [String] user_id: the id of the user in your application
+    # @param [Event] event: the events to track
+    # @param [Itly::PluginCallOptions] options: plugin specific option.
+    #
+    def track(user_id:, event:, options: nil); end
+
+    def post_track(user_id:, event:, validation_results:); end
+
+    ##
+    # Associate one user ID with another (typically a known user ID with an anonymous one).
+    #
+    # @param [String] user_id: The ID that the user will be identified by going forward.
+    # @param [String] previous_id: The ID the user has been identified by so far.
+    # @param [Itly::PluginCallOptions] options: plugin specific option.
+    #
+    def alias(user_id:, previous_id:, options: nil); end
+
+    def post_alias(user_id:, previous_id:); end
+
+    ##
+    # Flush data
+    #
+    def flush; end
+
+    ##
+    # Stop all processes and free resources.
+    #
+    def shutdown; end
+
+    ##
+    # Reset the SDK's (and all plugins') state. This method is usually called when a user logs out.
+    #
+    def reset; end
+
+    ##
+    # Validate an Event
+    #
+    # See +Itly#validate+ for more information
+    #
+    # Your plugin can return a +Itly::ValidationResponse+ object to provide success status
+    # and validation message; otherwise it can return +nil+ which will be interpreted as valid=true
+    #
+    def validate(event:); end
+
+    ##
+    # Get the plugin ID, which is the underscored class name. Use only the child class in case of nested classes
+    #
+    # @return [String] plugin id
+    #
+    def id
+      name = (self.class.name || 'UnknownPluginClass').gsub('::', '-')
+      name = (name || 'UnknownPluginClass').gsub(/([A-Z]+)/, '_\1').gsub(/-_/, '-').sub(/^_/, '').sub(/^itly-/i, '')
+      name.downcase
+    end
+  end
+end

data/lib/itly/plugin_call_options.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # PluginCallOptions virtual class
+  # Parent class of plugin specific options
+  #
+  class PluginCallOptions
+    ##
+    # Inspect the object
+    #
+    # @return [String] the object description
+    #
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/itly/plugin_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Itly main class
+class Itly
+  ##
+  # PluginOptions class for Itly Plugins #load methods
+  #
+  # +environment+: A Symbol specifying the environment the Itly SDK is running in.  #
+  # +logger+: Allow to set a custom Logger.
+  #
+  class PluginOptions
+    attr_reader :environment, :logger
+
+    ##
+    # Create a new PluginOptions object
+    #
+    def initialize(environment:, logger:)
+      @environment = environment
+      @logger = logger
+    end
+  end
+end

data/lib/itly/plugins.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Itly main class
+class Itly
+  ##
+  # Manage list of Plugins
+  #
+  module Plugins
+    private
+
+    # Yield the block with each instanciated plugin
+    def run_on_plugins
+      raise 'Need a block' unless block_given?
+
+      options.plugins.collect do |plugin|
+        yield plugin
+      rescue StandardError => e
+        logger&.error "Itly Error in #{plugin.class.name}. #{e.class.name}: #{e.message}"
+        raise e if options.development?
+
+        nil
+      end.compact
+    end
+  end
+end

data/lib/itly/validation_response.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Itly
+  ##
+  # Contains the result of a validation
+  #
+  # +valid+: [True/False] indicating if the validation succeeded or failed
+  # +plugin_id+: [String] an id identifying your plugin
+  # +message+: [String] the message you want to appear in the logs in case of error
+  #
+  class ValidationResponse
+    attr_reader :valid, :plugin_id, :message
+
+    ##
+    # Create a new ValidationResponse object
+    #
+    def initialize(valid:, plugin_id:, message: '')
+      @valid = valid
+      @plugin_id = plugin_id
+      @message = message
+    end
+
+    ##
+    # Describe the object
+    #
+    # @return [String] the object description
+    #
+    def to_s
+      "#<#{self.class.name}: valid: #{valid}, plugin_id: #{plugin_id}, message: #{message}>"
+    end
+
+    ##
+    # Inspect the object
+    #
+    # @return [String] the object description
+    #
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/itly/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Itly main class
+class Itly
+  VERSION = '0.1.0'
+end