evvnt 0.1.0

data/lib/evvnt/base.rb

@@ -0,0 +1,166 @@
+module Evvnt
+  # Internal: Base class for Evvnt API resource classes.
+  #
+  class Base
+    # frozen_string_literal: true
+
+    require "evvnt/actions"
+    require "evvnt/api"
+    require "evvnt/class_template_methods"
+    require "evvnt/instance_template_methods"
+    require "evvnt/logging"
+    require "evvnt/nested_resources"
+    require "evvnt/path_helpers"
+    require "evvnt/persistence"
+
+    include HTTParty
+    include Logging
+    include Api
+    include Persistence
+    extend PathHelpers
+    extend NestedResources
+    extend Actions
+
+    ##
+    # Test if a String is a date string.
+    DATE_STRING_REGEX = /^\d{4}-\d{2}-\d{2}$/
+
+    ##
+    # Test if a String is a datetime string.
+    DATETIME_STRING_REGEX = /^\d{4}-\d\d-\d\dT\d\d\:\d\d\:\d\d\+\d\d\:\d\d$/
+
+
+    if Evvnt.configuration.environment == :live
+      base_uri "https://api.evvnt.com"
+    else
+      base_uri "https://api.sandbox.evvnt.com"
+    end
+
+    ##
+    # The attributes for this given record
+    #
+    # Returns Hash
+    attr_reader :attributes
+
+    # =================
+    # = Class Methods =
+    # =================
+
+    ##
+    # The first record from the API index actions
+    #
+    # Returns {Evvnt::Base} subclass
+    def self.first
+      defined_actions.include?(:index) ? all.first : method_missing(:first)
+    end
+
+    ##
+    # The last record from the API index actions
+    #
+    # Returns {Evvnt::Base} subclass
+    def self.last
+      defined_actions.include?(:index) ? all.first : method_missing(:last)
+    end
+
+
+    # ====================
+    # = Instance methods =
+    # ====================
+
+    ##
+    # Initialize a new record
+    #
+    # attributes - A Hash of attributes for the given record. See {method_missing} for
+    #              more info on how this is handled.
+    def initialize(attributes = {})
+      self.attributes = Hash[attributes.map { |k, v| [k, format_attribute(k, v)] }]
+    end
+
+    ##
+    # Set or change the attributes for this record
+    #
+    # hash - A Hash of attributes for this record.
+    #
+    # Returns Hash
+    def attributes=(hash)
+      @attributes = Hash(hash).with_indifferent_access
+    end
+
+    # The unique identifier for the given record. Tries +uuid+ followed by +id+.
+    #
+    # Returns String
+    def unique_identifier
+      attributes["uuid"] || attributes["id"]
+    end
+
+    private
+
+    def format_attribute(key, value)
+      case value
+      when String
+        format_string_attribute(value)
+      when Array
+        format_array_attribute(key, value)
+      when Hash
+        format_hash_attribute(key, value)
+      else
+        value
+      end
+    end
+
+    def format_hash_attribute(key, value)
+      unless Evvnt.const_defined?(key.singularize.classify)
+        raise ArgumentError, "Unknown object type: #{key}"
+      end
+      Evvnt.const_get(key.singularize.classify).new(value)
+    end
+
+    def format_array_attribute(key, value)
+      Array(value).map do |attributes|
+        unless Evvnt.const_defined?(key.singularize.classify)
+          raise ArgumentError, "Unknown object type: #{key}"
+        end
+        Evvnt.const_get(key.singularize.classify).new(attributes)
+      end
+    end
+
+    def format_string_attribute(value)
+      case value
+      when DATE_STRING_REGEX
+        value.to_date
+      when DATETIME_STRING_REGEX
+        value.to_datetime
+      else
+        value
+      end
+    end
+
+    ##
+    # Overrides method missing to catch undefined methods. If +method_name+ is one
+    # of the keys on +attributes+, returns the value of that attribute. If +method_name+
+    # is not one of +attributes+, passes up the chain to super.
+    #
+    # method_name - Symbol of the name of the method we're testing for.
+    # args        - Array of arguments send with the original mesage.
+    # block       - Proc of code passed with original message.
+    #
+    def method_missing(method_name, *args)
+      if method_name.to_s[/\=/]
+        attributes[method_name.to_s.gsub(/\=+/, "")] = args.first
+      else
+        attributes[method_name.to_s.gsub(/\=+/, "")]
+      end
+    end
+
+    ##
+    # Improve code instrospect. Allows `respond_to?` for dynamically added attribute
+    # methods.
+    #
+    # method - A Symbol with the method name
+    #
+    # Returns Boolean
+    def respond_to_missing?(method, *)
+      attributes.stringify_keys.keys.include?(method.to_s) || super
+    end
+  end
+end

data/lib/evvnt/broadcast.rb

@@ -0,0 +1,4 @@
+module Evvnt
+  class Broadcast < Evvnt::Base
+  end
+end

data/lib/evvnt/broadcast_result.rb

@@ -0,0 +1,4 @@
+module Evvnt
+  class BroadcastResult < Evvnt::Base
+  end
+end

data/lib/evvnt/category.rb

@@ -0,0 +1,17 @@
+module Evvnt
+  # Fetch EVVNT Categories from the API
+  class Category < Evvnt::Base
+
+    ##
+    # The ID of the "All" category on Evvnt
+    DEFAULT_ID = 26
+
+    ##
+    # GET /categories List categories
+    # Returns Array
+    define_action :index
+
+    belongs_to :publisher
+
+  end
+end

data/lib/evvnt/class_template_methods.rb

@@ -0,0 +1,101 @@
+module Evvnt
+  # Internal: Template methods to provide default behaviour for API actions.
+  #
+  # These are defined on Evvnt::Base subclasses where required to map the Evvnt API
+  # actions.
+  module ClassTemplateMethods
+    # frozen_string_literal: true
+
+    ##
+    # Regular expression for params in URL strings
+    PARAM_REGEX = %r{\:[^\/$]+}
+
+    # Template method for creating a new record on the API.
+    #
+    # params - A Hash of params to send to the API.
+    #
+    # Returns {Evvnt::Base} subclass
+    def create(**params)
+      path = if params_include_parent_resource_id?(params)
+               nest_path_within_parent(plural_resource_path, params)
+             else
+               plural_resource_path
+             end
+      api_request(:post, path, params: params)
+    end
+
+    # Template method for fetching an index of record from the API.
+    #
+    # params - A Hash of params to send to the API.
+    #
+    # Returns Array
+    def index(**params)
+      params.stringify_keys!
+      if plural_resource_path.respond_to?(:call)
+        path = plural_resource_path.call
+        path.match(PARAM_REGEX) do |segment|
+          value = params.delete(segment.to_s[1..-1])
+          path  = path.gsub!(/#{segment}/, value.to_s)
+        end
+      else
+        path = plural_resource_path
+      end
+      if params_include_parent_resource_id?(params)
+        path = nest_path_within_parent(path, params)
+      end
+      api_request(:get, path, params: params)
+    end
+
+    # Template method for creating a given record
+    #
+    # record_id - An Integer or String representing the record ID on the API.
+    # params    - A Hash of params to send to the API.
+    #
+    # Returns {Evvnt::Base} subclass
+    def show(record_id = nil, **params)
+      if record_id.nil? && !singular_resource?
+        raise ArgumentError, "record_id cannot be nil"
+      end
+      path = singular_path_for_record(record_id, params)
+      api_request(:get, path, params: params)
+    end
+
+    # Template method for updating a given record
+    #
+    # record_id - An Integer or String representing the record ID on the API.
+    # params    - A Hash of params to send to the API.
+    #
+    # Returns {Evvnt::Base} subclass
+    def update(record_id, **params)
+      if record_id.nil? && !singular_resource?
+        raise ArgumentError, "record_id cannot be nil"
+      end
+      path = singular_path_for_record(record_id, params)
+      api_request(:put, path, params: params)
+    end
+
+    # Template method for fetching _mine_ records from the API.
+    #
+    # record_id - An Integer or String representing the record ID on the API (optional).
+    # params    - A Hash of params to send to the API.
+    #
+    # Returns Array
+    # Returns {Evvnt::Base}
+    def ours(record_id = nil, **params)
+      id_segment = record_id.to_s
+      segments   = [plural_resource_path, "ours", id_segment].select(&:present?)
+      path       = File.join(*segments).to_s
+      api_request(:get, path, params: params)
+    end
+
+    # Template method for fetching _mine_ records from the API.
+    #
+    # params    - A Hash of params to send to the API.
+    #
+    # Returns Array
+    def mine(**params)
+      path = File.join(plural_resource_path, "mine").to_s
+      api_request(:get, path, params: params)
+    end
+  end
+end

data/lib/evvnt/clicks_by_day.rb

@@ -0,0 +1,4 @@
+module Evvnt
+  class ClicksByDay < Evvnt::Base
+  end
+end

data/lib/evvnt/configuration.rb

@@ -0,0 +1,54 @@
+module Evvnt
+  # Handles configuration for the gem
+  class Configuration
+
+    ##
+    #
+    ENVIRONMENTS = %i[sandbox live].freeze
+
+
+    ##
+    #
+    attr_writer :logger
+
+    ##
+    #
+    attr_writer :debug
+
+    ##
+    #
+    attr_accessor :api_key
+
+    ##
+    #
+    attr_accessor :api_secret
+
+    def initialize(&block)
+      instance_eval(&block) if block_given?
+    end
+
+    ##
+    #
+    def environment=(value)
+      raise ArgumentError unless value.to_sym.in?(ENVIRONMENTS)
+      @environment = value
+    end
+
+    def environment
+      @environment ||= :sandbox
+    end
+
+    ##
+    #
+    def logger
+      @logger ||= Logger.new($stdout)
+    end
+
+    ##
+    #
+    def debug
+      defined?(@debug) ? @debug : @debug = false
+    end
+
+  end
+end

data/lib/evvnt/contact.rb

@@ -0,0 +1,4 @@
+module Evvnt
+  class Contact < Evvnt::Base
+  end
+end

data/lib/evvnt/contract.rb

@@ -0,0 +1,18 @@
+module Evvnt
+  # Public: Returns contract info from the EVVNT API
+  class Contract < Evvnt::Base
+
+    ##
+    # The JSON key for the package data from the API response.
+    OBJECT_KEY = "package_options".freeze
+
+    singular_resource!
+
+    ##
+    # GET /contract Get contract information
+    define_action :index do
+      api_request(:get, plural_resource_path, options: { object: OBJECT_KEY })
+    end
+
+  end
+end

data/lib/evvnt/event.rb

@@ -0,0 +1,69 @@
+module Evvnt
+  # Public: Returns events info from the EVVNT API
+  class Event < Evvnt::Base
+
+    ##
+    # GET /events List Events
+    define_action :index
+
+    ##
+    # GET /events/:event_id Get one event
+    define_action :show
+
+    ##
+    # POST /events  Create an event
+    define_action :create
+
+    ##
+    # PUT /events/:event_id  Update an event
+    define_action :update
+
+    ##
+    # GET /events/ours(/:id) Get events of you and your created users
+    define_action :ours
+
+    ##
+    # GET /events/mine  List my events
+    define_action :mine
+
+
+    private
+
+
+    def format_hash_attribute(key, value)
+      case key
+      when "links"
+        format_links_attribute(key, value)
+      when "prices"
+        format_prices_attribute(key, value)
+      else
+        super
+      end
+    end
+
+    def format_array_attribute(key, value)
+      case key
+      when /^(image\_urls|sub\_category\_ids)$/
+        send(:"format_#{key}_attribute", key, value)
+      else
+        super
+      end
+    end
+
+    def format_image_urls_attribute(_key, value)
+      value
+    end
+
+    def format_sub_category_ids_attribute(_key, value)
+      value
+    end
+
+    def format_links_attribute(_key, value)
+      value.to_a.map { |name, url| Evvnt::Link.new(name: name, url: url) }
+    end
+
+    def format_prices_attribute(_key, value)
+      value.to_a.map { |name, price| Evvnt::Price.new(name: name, value: price) }
+    end
+  end
+end

data/lib/evvnt/instance_template_methods.rb

@@ -0,0 +1,17 @@
+module Evvnt
+  # Internal: Template methods to provide default behaviour for API actions.
+  #
+  # These are defined on Evvnt::Base subclasses where required to map the Evvnt API
+  # actions.
+  module InstanceTemplateMethods
+    # Template method for updating a given record
+    #
+    # record_id - An Integer or String representing the record ID on the API.
+    # params    - A Hash of params to send to the API.
+    #
+    # Returns {Evvnt::Base} subclass
+    def update(**new_attributes)
+      self.class.update(id, new_attributes) unless new_attributes == attributes
+    end
+  end
+end

data/lib/evvnt/link.rb

@@ -0,0 +1,5 @@
+module Evvnt
+  class Link < Evvnt::Base
+
+  end
+end

data/lib/evvnt/logging.rb

@@ -0,0 +1,42 @@
+module Evvnt
+  # Internal: Log messages for debugging
+  #
+  module Logging
+    extend ActiveSupport::Concern
+
+    ##
+    # The tag to print to the logger.
+    TAG_NAME = 'EVVNT'.freeze
+
+    private
+
+    # The Logger object to print out messages to.
+    def logger
+      Evvnt.configuration.logger
+    end
+
+    # Print a debug level message
+    #
+    # message - A String of the message to be printed.
+    def debug(message)
+      log_message(:debug, message)
+    end
+
+    # Log a message to the {logger} with the given log level
+    #
+    # level   - A Symbol representing the logger level
+    # message - A String with the message to print to the log
+    def log_message(level, message)
+      if logger.respond_to?(:tagged)
+        logger.tagged(TAG_NAME) { |l| l.public_send(level, message) }
+      else
+        logger.public_send(level, message)
+      end
+    end
+
+    # rubocop:disable Naming/ConstantName
+    # Make these methods available to the class when module is included.
+    ClassMethods = self
+    # rubocop:enable Naming/ConstantName
+  end
+end

data/lib/evvnt/nested_resources.rb

@@ -0,0 +1,66 @@
+module Evvnt
+  # Internal: Adds behaviour to {Evvnt::Base} for handling nested resources
+  #
+  # Examples
+  #
+  #   class Thing < Evvnt::Base
+  #     belongs_to :user
+  #   end
+  #   # Will find a Thing at "/users/456/things/123.json"
+  #   @thing = Thing.find("123", user_id: "456")
+  #
+  module NestedResources
+    # frozen_string_literal: true
+
+    private
+
+      # Tell a class that it's resources may be nested within another named resource
+      #
+      # parent_resource - A Symbol with the name of the parent resource.
+      #
+      def belongs_to(parent_resource)
+        parent_resource = parent_resource.to_sym
+        parent_resources << parent_resource unless parent_resource.in?(parent_resources)
+      end
+
+      # A list of the parent resources for this class.
+      #
+      # Return Array
+      def parent_resources
+        @parent_resources ||= []
+      end
+
+      # A list of the param names that represent parent resources
+      #
+      # Returns Array
+      def parent_resource_id_params
+        parent_resources.map { |pr| :"#{pr}_id" }
+      end
+
+      # Does the params hash contain a parent resource ID?
+      #
+      # params - A Hash of params to send to the API.
+      #
+      # Returns Boolean
+      def params_include_parent_resource_id?(params)
+        parent_resource_param(params).present?
+      end
+
+      # The param that represents the parent record (e.g. +:user_id+)
+      #
+      # params - A Hash of params to send to the API.
+      #
+      # Returns Symbol
+      def parent_resource_param(params)
+        (params.symbolize_keys.keys & parent_resource_id_params).first
+      end
+
+      # The name of the parent record defined in the parms
+      #
+      # params - A Hash of params to send to the API.
+      #
+      def parent_resource_name(params)
+        parent_resource_param(params).to_s.gsub(/\_id/, '').pluralize
+      end
+  end
+end

data/lib/evvnt/package.rb

@@ -0,0 +1,24 @@
+module Evvnt
+  # Public: Represents the packages resources on the EVVNT API.
+  class Package < Evvnt::Base
+
+    ##
+    # GET /users/:user_id/packages Lists all of the packages belonging to a user
+    define_action :index
+
+    ##
+    # POST /packages Create a package
+    define_action :create
+
+    ##
+    # GET /packages/:package_id Get the details of a package
+    define_action :show
+
+    ##
+    # GET /packages/mine List my packages
+    define_action :mine
+
+    belongs_to :user
+
+  end
+end