alula-ruby 0.50.1

data/lib/alula/rpc_response.rb

@@ -0,0 +1,14 @@
+module Alula
+  class RpcResponse
+    attr_accessor :request_id, :result, :data
+
+    def initialize(response)
+      @request_id = response.data['id']
+      @result = response.data['result']
+    end
+
+    def ok?
+      @result['success'] == true || (@result['errors'].nil? && @result['error'].nil?)
+    end
+  end
+end

data/lib/alula/singleton_rest_resource.rb

@@ -0,0 +1,26 @@
+module Alula
+  class SingletonRestResource < ApiResource
+    def self.resource_url
+      if self == SingletonRestResource
+        raise NotImplementedError, "SingletonRestResource is an abstract class.  You should perform actions on its subclasses (Self, etc.)"
+      end
+      # Namespaces are separated in object names with periods (.) and in URLs
+      # with forward slashes (/), so replace the former with the latter.
+      "/rest/v1/#{self.get_resource_path}"
+    end
+
+    def resource_url
+      self.class.resource_url
+    end
+
+    def self.retrieve
+      instance = new
+      instance.refresh
+      instance
+    end
+
+    def initialize(attributes = {})
+      super(nil, attributes)
+    end
+  end
+end

data/lib/alula/util.rb

@@ -0,0 +1,107 @@
+module Alula
+  class Util
+    class << self
+      #
+      # Some fields use odd casing (abbreviations mostly) that require a strict mapping
+      # for camelization to work properly
+      CAMELIZE_MAPPING = {
+        'ce_arming_supervision_trouble_zones' => 'CEArmingSupervisionTroubleZones'
+      }.freeze
+
+      # Based on ActiveSupport's underscore method
+      # activesupport/lib/active_support/inflector/methods.rb, line 90
+      def underscore(camel_cased_word)
+        return camel_cased_word unless camel_cased_word =~ /[A-Z-]|::/
+        word = camel_cased_word.to_s.gsub(/::/, '/')
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+      # Check if BVN hex conversion needed
+      def convert_hex_crc?(value)
+        [32, 33, 34, 35].include? value
+      end
+
+      def camelize(under_scored_word)
+        return CAMELIZE_MAPPING[under_scored_word.to_s] if CAMELIZE_MAPPING.key?(under_scored_word.to_s)
+        words = under_scored_word.to_s.split(/-|_/)
+        words.each_with_index.map{ |el, i| i == 0 ? el.downcase : el.capitalize }.join
+      end
+
+      def upper_camelcase(under_scored_word)
+        under_scored_word.to_s.split(/-|_/).map(&:capitalize).join
+      end
+
+      def split_on_word(string, separator_match = /-|_/, &block)
+        string.to_s.split(separator_match)
+      end
+
+      # https://stackoverflow.com/questions/9381553/ruby-merge-nested-hash
+      def deep_merge(first, second)
+        merger = proc do |key, v1, v2|
+          if Hash === v1 && Hash === v2
+            v1.merge(v2, &merger)
+          elsif Array === v1 && Array === v2
+            v1 | v2
+          elsif [:undefined, nil, :nil].include?(v2)
+            v1
+          else
+            v2
+          end
+        end
+
+        first.merge(second.to_h, &merger)
+      end
+
+      def model_errors_from_response(response)
+        errors = response.data['errors']
+        return false unless errors
+
+        error_object = errors.each_with_object({}) do |err, collector|
+          #
+          # This is duplicitive but it ensures that the model
+          # itself will have _some_ kind of error detail if we need to print that out.
+          collector[:model] ||= []
+          collector[:model] << err['detail']
+
+          # Error objects contain a bunch of info, but all the good stuff
+          # is stored in a sub-object named meta
+          # 
+          # meta looks something like this
+          # {
+          #   fieldName: 'field error description',
+          #   context: {
+          #     // extra info about the request
+          #   }
+          # }
+          # We need the fieldName to join errors to fields, and context gives extra
+          # info that's good for debugging.
+          err['meta']&.each_pair do |attribute, val|
+            if attribute == 'context'
+              collector[:context] ||= []
+              collector[:context] << val
+            else
+              underscore_field = Alula::Util.underscore(attribute).to_sym
+              collector[underscore_field] = val
+            end
+          end
+        end
+
+        #
+        # De-duplicate context so we don't have the same info (requestId)
+        # existing for every field that failed.
+        error_object[:context] = error_object[:context].uniq.compact if error_object[:context]
+
+        #
+        # We have UI clients that depend on this being a string.
+        # TODO: Update clients and let this be an array?
+        error_object[:model] = error_object[:model].uniq.compact.join(', ')
+
+        error_object
+      end
+    end
+  end
+end

data/lib/alula/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Alula
+  VERSION = '0.50.1'
+end

data/lib/alula.rb

@@ -0,0 +1,135 @@
+require 'alula/version'
+require 'request_store'
+require 'forwardable'
+
+require_relative 'alula/resource_attributes'
+require_relative 'alula/relationship_attributes'
+require_relative 'alula/api_operations/list'
+require_relative 'alula/api_operations/request'
+require_relative 'alula/api_operations/save'
+require_relative 'alula/api_operations/delete'
+require_relative 'alula/api_resource'
+require_relative 'alula/rpc_resource'
+require_relative 'alula/rpc_response'
+require_relative 'alula/rest_resource'
+require_relative 'alula/meta'
+require_relative 'alula/pagination'
+require_relative 'alula/singleton_rest_resource'
+require_relative 'alula/alula_response'
+require_relative 'alula/filter_builder'
+require_relative 'alula/query_interface'
+require_relative 'alula/util'
+require_relative 'alula/rate_limit'
+
+require_relative 'alula/errors'
+require_relative 'alula/client'
+require_relative 'alula/list_object'
+require_relative 'alula/oauth'
+
+require_relative 'alula/helpers/device_attribute_translations'
+
+require_relative 'alula/resources/billing_program'
+require_relative 'alula/resources/device'
+require_relative 'alula/resources/device_charge'
+require_relative 'alula/resources/device_event_log'
+require_relative 'alula/resources/device_cellular_status'
+require_relative 'alula/resources/device_program'
+require_relative 'alula/resources/dealer_address'
+require_relative 'alula/resources/dealer_account_transfer'
+require_relative 'alula/resources/dealer_suspension_log'
+require_relative 'alula/resources/dealer_program'
+require_relative 'alula/resources/event_trigger'
+require_relative 'alula/resources/event_webhook'
+require_relative 'alula/resources/self'
+require_relative 'alula/resources/user'
+require_relative 'alula/resources/admin_user'
+require_relative 'alula/resources/user_phone'
+require_relative 'alula/resources/user_address'
+require_relative 'alula/resources/user_pushtoken'
+require_relative 'alula/resources/user_preferences'
+require_relative 'alula/resources/user_videoprofile'
+require_relative 'alula/resources/dealer'
+require_relative 'alula/resources/dealer_branding'
+require_relative 'alula/resources/token_exchange'
+require_relative 'alula/resources/receiver_connection'
+require_relative 'alula/resources/receiver_group'
+require_relative 'alula/resources/revision'
+require_relative 'alula/resources/station'
+
+require_relative 'alula/resources/feature_plan'
+require_relative 'alula/resources/feature_planvideo'
+require_relative 'alula/resources/feature_price'
+require_relative 'alula/resources/feature_bysubject'
+
+require_relative 'alula/procedures/device_cellular_history_proc'
+require_relative 'alula/procedures/device_rateplan_get_proc'
+require_relative 'alula/procedures/device_register_proc'
+require_relative 'alula/procedures/device_unregister_proc'
+require_relative 'alula/procedures/device_assign_proc'
+require_relative 'alula/procedures/device_unassign_proc'
+require_relative 'alula/procedures/device_signal_add_proc'
+require_relative 'alula/procedures/device_signal_update_proc'
+require_relative 'alula/procedures/device_signal_delivered_proc'
+require_relative 'alula/procedures/dealer_device_stats_proc'
+require_relative 'alula/procedures/dealer_suspend_proc'
+require_relative 'alula/procedures/dealer_restore_proc'
+require_relative 'alula/procedures/upload_touchpad_branding_proc'
+require_relative 'alula/procedures/user_transfer_request'
+require_relative 'alula/procedures/user_transfer_cancel'
+require_relative 'alula/procedures/user_transfer_authorize'
+require_relative 'alula/procedures/user_transfer_deny'
+require_relative 'alula/procedures/user_transfer_reject'
+require_relative 'alula/procedures/user_transfer_accept'
+require_relative 'alula/procedures/user_plansvideo_price_get'
+
+module Alula
+  #
+  # A map of API REST resource names to Alula Ruby classes
+  # {
+  #   'feature-plansvideo' => Alula::FeaturePlanVideo
+  # }
+  # This is used to determine which class to initialize when working with
+  # API query responses, and included models.
+  @@resource_map = [
+    Alula::BillingProgram,
+    Alula::Device,
+    Alula::DeviceCharge,
+    Alula::DeviceEventLog,
+    Alula::DeviceProgram,
+    Alula::DealerAddress,
+    Alula::DealerProgram,
+    Alula::DeviceCellularStatus,
+    Alula::Self,
+    Alula::User,
+    Alula::AdminUser,
+    Alula::UserPhone,
+    Alula::UserAddress,
+    Alula::UserPushtoken,
+    Alula::UserPreferences,
+    Alula::UserVideoProfile,
+    Alula::Dealer,
+    Alula::DealerBranding,
+    Alula::ReceiverGroup,
+    Alula::Station,
+    Alula::DealerAccountTransfer,
+    Alula::FeaturePlan,
+    Alula::FeaturePlanVideo,
+    Alula::FeaturePrice,
+    Alula::FeatureBySubject,
+  ].each_with_object({}) do |klass, resource_map|
+    resource_map[klass.get_type] = klass
+  end
+
+  def self.class_from_resource_type(type)
+    @@resource_map[type] || (raise "Unknown resource name #{type}, you need to map this "\
+                                   'name to a class in the Alula module.')
+  end
+
+  def self.logger
+    RequestStore.store['logger'] ||= defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+  end
+
+  def self.logger=(logger)
+    RequestStore.store['logger'] = logger
+  end
+end

data/lib/parser.rb

@@ -0,0 +1,199 @@
+module Parser
+  class Files
+    NAMES_TO_RESOURCES = {
+      /Alula_API_Documentation_([0-9]{4})-([0-9]{2})-([0-9]{2}).html/ => :reqresp,
+      /Alula_Connect_Plus_API_Documentation_([0-9]{4})-([0-9]{2})-([0-9]{2}).html/ => :helix
+    }.freeze
+
+    class << self
+      def load
+        NAMES_TO_RESOURCES.each.each_with_object({}) do |(regex, category), coll|
+          coll[category] = find_latest_file(regex)
+        end
+      end
+
+      def find_latest_file(pattern)
+        Dir.glob('./data/docs/*').grep(pattern).first
+      end
+    end
+  end
+
+  class Engine
+    DELIMITER = 'hr'
+    METHOD_TYPE_REGEX = /Method:|Resource:/
+    REST_METHOD_TYPE = /Resource:/
+    RPC_METHOD_TYPE = /Method:/
+
+    class << self
+      #
+      # Documentation is a flat structure. HRs split resources, and all elements
+      # for each resource are siblings. This walks through the document and pulls out
+      # data into a structured hash suitable for further parsing.
+      # There are better ways to do this parsing. This is the quick, brute-force way.
+      # Note, this implementation uses parse exceptions to indicate the end of parsing.
+      # This will be fragile but works for now.
+      def parse_doc(category, file)
+        doc = Nokogiri::HTML(File.open(file).read)
+
+        structured = []
+
+        datum_structure = {
+          type: 'This will be rest or rpc',
+          name: 'This will be a resource name',
+          path: 'This will be the resource path',
+          methods: 'This will be a list of supported methods',
+          description: 'This will be a description of the resource',
+          relationships: 'This will be the relationships',
+          parameters: 'This will be the parameters',
+          fields: 'This will be the fields'
+        }
+
+        current_datum = nil
+
+        # Parse REST docs.
+        doc.css('#mainContent').children.each do |node|
+          next if node.name != DELIMITER
+          structured << current_datum if current_datum
+          current_datum = datum_structure.dup
+          current_datum = parse_chunk(current_datum, node) rescue nil
+        end
+
+        # Parse RPC docs
+        rpc_found = false
+        current_datum = nil
+        doc.css('#mainContent').children.each do |node|
+          # Skip forward until we get to the RPC section
+          unless rpc_found
+            if node.name == 'h1' and node.text =~ /RPC API/
+              rpc_found = true
+            else
+              next
+            end
+          end
+
+          next if node.name != DELIMITER
+
+          structured << current_datum if current_datum
+          current_datum = datum_structure.dup
+          current_datum = parse_chunk(current_datum, node) rescue nil
+        end
+
+        structured
+      end
+
+      private
+
+      def parse_chunk(current_datum, node)
+        current_datum[:type] = find_type(node)
+        current_datum[:name] = find_name(node).strip
+        current_datum[:path] = find_path(node).strip
+        current_datum[:description] = find_description(node).strip
+        current_datum[:parameters] = find_parameters(node)
+        
+        if current_datum[:type] == :rest
+          current_datum[:methods] = find_methods(node)
+          current_datum[:relationships] = find_relationships(node)
+          current_datum[:fields] = find_fields(node)
+        else
+          current_datum[:methods] = false
+          current_datum[:relationships] = false
+          current_datum[:fields] = false
+        end
+        current_datum
+      end
+
+      def find_type(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ METHOD_TYPE_REGEX
+        if sibling.text =~ RPC_METHOD_TYPE
+          return :rpc
+        elsif sibling.text =~ REST_METHOD_TYPE
+          return :rest
+        end
+      end
+
+      def find_name(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ METHOD_TYPE_REGEX
+        sibling.text.gsub(METHOD_TYPE_REGEX, '')
+      end
+
+      def find_path(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Base URL/
+        sibling = sibling.next_sibling until sibling.name == 'p'
+        sibling.css('code').text
+      end
+
+      def find_methods(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Available methods/
+        sibling.css('code').map { |el| el.text }
+      end
+
+      def find_description(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Description/
+        sibling = sibling.next_sibling
+        text = []
+        until sibling.name == 'h3'
+          text << sibling.text
+          sibling = sibling.next_sibling
+        end
+        text.join('')
+      end
+
+      def find_relationships(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Relationships/
+        case sibling.next_sibling.next_sibling.name
+        when 'p'
+          return false
+        when 'table'
+          return table_to_hash(sibling.next_sibling.next_sibling)
+        else
+          raise 'WTF nothing?'
+        end
+      end
+
+      def find_parameters(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Parameters/
+        case sibling.next_sibling.next_sibling.name
+        when 'p'
+          return false
+        when 'table'
+          return table_to_hash(sibling.next_sibling.next_sibling)
+        else
+          raise 'WTF nothing?'
+        end
+      end
+
+      def find_fields(node)
+        sibling = node.next_sibling
+        sibling = sibling.next_sibling until sibling.text =~ /Fields/
+        case sibling.next_sibling.next_sibling.name
+        when 'p'
+          return false
+        when 'table'
+          return table_to_hash(sibling.next_sibling.next_sibling)
+        else
+          raise 'WTF nothing?'
+        end
+      end
+
+      #
+      # Transform an HTML table with headers into an array of objects.
+      # Object keys are table header text, values are cell value text
+      def table_to_hash(node)
+        headers = node.css('thead th').map { |el| el.text.downcase }
+        node.css('tbody tr').each_with_object([]) do |row, coll|
+          vals = row.css('td').map { |c| c.text }
+          coll << headers.each_with_index.each_with_object({}) do |(header, index), collector|
+            collector[header] = vals[index]
+          end
+        end
+      end
+    end
+  end
+end