RubyGems - alula-ruby - Versions diffs - 0.50.1 - Mend

alula-ruby 0.50.1

Files changed (102) hide show

checksums.yaml +7 -0
data/.circleci/config.yml +14 -0
data/.env.example +8 -0
data/.github/workflows/gem-push.yml +45 -0
data/.gitignore +23 -0
data/.rspec +3 -0
data/.travis.yml +7 -0
data/Dockerfile +6 -0
data/Gemfile +12 -0
data/Guardfile +42 -0
data/README.md +423 -0
data/Rakefile +6 -0
data/VERSION.md +84 -0
data/alula-docker-compose.yml +80 -0
data/alula.gemspec +38 -0
data/bin/console +15 -0
data/bin/docparse +36 -0
data/bin/genresource +79 -0
data/bin/setup +8 -0
data/bin/testauth +24 -0
data/bin/testprep +9 -0
data/data/docs/Alula_API_Documentation_2021-04-06.html +16240 -0
data/docker-compose.yml +11 -0
data/lib/alula/alula_response.rb +20 -0
data/lib/alula/api_operations/delete.rb +52 -0
data/lib/alula/api_operations/list.rb +45 -0
data/lib/alula/api_operations/request.rb +44 -0
data/lib/alula/api_operations/save.rb +81 -0
data/lib/alula/api_resource.rb +196 -0
data/lib/alula/client.rb +142 -0
data/lib/alula/errors.rb +169 -0
data/lib/alula/filter_builder.rb +271 -0
data/lib/alula/helpers/device_attribute_translations.rb +68 -0
data/lib/alula/list_object.rb +64 -0
data/lib/alula/meta.rb +16 -0
data/lib/alula/monkey_patches.rb +24 -0
data/lib/alula/oauth.rb +118 -0
data/lib/alula/pagination.rb +25 -0
data/lib/alula/procedures/dealer_device_stats_proc.rb +16 -0
data/lib/alula/procedures/dealer_restore_proc.rb +25 -0
data/lib/alula/procedures/dealer_suspend_proc.rb +25 -0
data/lib/alula/procedures/device_assign_proc.rb +23 -0
data/lib/alula/procedures/device_cellular_history_proc.rb +33 -0
data/lib/alula/procedures/device_rateplan_get_proc.rb +21 -0
data/lib/alula/procedures/device_register_proc.rb +31 -0
data/lib/alula/procedures/device_signal_add_proc.rb +42 -0
data/lib/alula/procedures/device_signal_delivered_proc.rb +31 -0
data/lib/alula/procedures/device_signal_update_proc.rb +32 -0
data/lib/alula/procedures/device_unassign_proc.rb +16 -0
data/lib/alula/procedures/device_unregister_proc.rb +21 -0
data/lib/alula/procedures/upload_touchpad_branding_proc.rb +24 -0
data/lib/alula/procedures/user_plansvideo_price_get.rb +21 -0
data/lib/alula/procedures/user_transfer_accept.rb +19 -0
data/lib/alula/procedures/user_transfer_authorize.rb +18 -0
data/lib/alula/procedures/user_transfer_cancel.rb +18 -0
data/lib/alula/procedures/user_transfer_deny.rb +19 -0
data/lib/alula/procedures/user_transfer_reject.rb +19 -0
data/lib/alula/procedures/user_transfer_request.rb +19 -0
data/lib/alula/query_interface.rb +142 -0
data/lib/alula/rate_limit.rb +11 -0
data/lib/alula/relationship_attributes.rb +107 -0
data/lib/alula/resource_attributes.rb +206 -0
data/lib/alula/resources/admin_user.rb +207 -0
data/lib/alula/resources/billing_program.rb +41 -0
data/lib/alula/resources/dealer.rb +218 -0
data/lib/alula/resources/dealer_account_transfer.rb +172 -0
data/lib/alula/resources/dealer_address.rb +89 -0
data/lib/alula/resources/dealer_branding.rb +226 -0
data/lib/alula/resources/dealer_program.rb +75 -0
data/lib/alula/resources/dealer_suspension_log.rb +49 -0
data/lib/alula/resources/device.rb +716 -0
data/lib/alula/resources/device_cellular_status.rb +134 -0
data/lib/alula/resources/device_charge.rb +70 -0
data/lib/alula/resources/device_event_log.rb +167 -0
data/lib/alula/resources/device_program.rb +54 -0
data/lib/alula/resources/event_trigger.rb +75 -0
data/lib/alula/resources/event_webhook.rb +47 -0
data/lib/alula/resources/feature_bysubject.rb +74 -0
data/lib/alula/resources/feature_plan.rb +57 -0
data/lib/alula/resources/feature_planvideo.rb +54 -0
data/lib/alula/resources/feature_price.rb +46 -0
data/lib/alula/resources/receiver_connection.rb +95 -0
data/lib/alula/resources/receiver_group.rb +74 -0
data/lib/alula/resources/revision.rb +91 -0
data/lib/alula/resources/self.rb +61 -0
data/lib/alula/resources/station.rb +130 -0
data/lib/alula/resources/token_exchange.rb +34 -0
data/lib/alula/resources/user.rb +229 -0
data/lib/alula/resources/user_address.rb +121 -0
data/lib/alula/resources/user_phone.rb +116 -0
data/lib/alula/resources/user_preferences.rb +57 -0
data/lib/alula/resources/user_pushtoken.rb +75 -0
data/lib/alula/resources/user_videoprofile.rb +38 -0
data/lib/alula/rest_resource.rb +17 -0
data/lib/alula/rpc_resource.rb +40 -0
data/lib/alula/rpc_response.rb +14 -0
data/lib/alula/singleton_rest_resource.rb +26 -0
data/lib/alula/util.rb +107 -0
data/lib/alula/version.rb +5 -0
data/lib/alula.rb +135 -0
data/lib/parser.rb +199 -0
metadata +282 -0

data/lib/alula/errors.rb ADDED Viewed

@@ -0,0 +1,169 @@
+module Alula
+  class AlulaError < StandardError
+    attr_reader :http_status, :raw_response, :error, :message
+    def initialize(error)
+      if error.class == String
+        @message = error
+        return
+      end
+      @http_status = error.http_status
+      @raw_response = error
+      @error = error.data['error']
+      @message = error.data['error_description'] || error.data['message']
+    end
+    def ok?
+      false
+    end
+    def self.for_response(response)
+      if !response.data['error'].nil? && !response.data['error'].empty?
+        self.error_for_response(response)
+      elsif !response.data['errors'].nil? && !response.data['errors'].empty?
+        self.errors_for_response(response)
+      elsif response.data.match(/^<!DOCTYPE html>/)
+        self.critical_error_for_response(response.data.scan(/<pre>(.*)<\/pre>/))
+      else
+        message = "Unable to derive error from response: #{response.inspect}"
+        Alula.logger.error message
+        raise UnknownApiError.new(message)
+      end
+    rescue NoMethodError
+      message = "Unable to derive error from response: #{response.inspect}"
+      Alula.logger.error message
+      raise UnknownApiError.new(message)
+    end
+    private
+    # Handle HTML-based errors from the API
+    def self.critical_error_for_response(error_text)
+      InvalidRequestError.new(error_text.first.first)
+    end
+    # Figure out what error should be raised
+    def self.error_for_response(response)
+      case response.data['error']
+      when 'RateLimit'
+        Alula.logger.error response
+        RateLimitError.new(response)
+      when 'invalid_token'
+        InvalidTokenError.new(response)
+      when 'insufficient_scope'
+        InsufficientScopeError.new(response)
+      when 'server_error'
+        Alula.logger.error response
+        ServerError.new(response)
+      else
+        #
+        # RPC errors are identified by jsonrpc in the body.
+        return ProcedureError.new(response) if response.data['jsonrpc']
+        Alula.logger.error response
+        raise NotImplementedError.new("Unable to derive error for #{response.data['error']}")
+      end
+    end
+    # Some responses have an error array. We won't be able to raise on all errors but we can raise on the first one
+    def self.errors_for_response(response)
+      error = response.data['errors'].first
+      case error['title']
+      when 'RateLimit'
+        RateLimitError.new(response)
+      when 'Forbidden'
+        ForbiddenError.new(error['detail'])
+      when 'Not Found'
+        NotFoundError.new(error['detail'])
+      when 'Bad Request'
+        Alula.logger.error response
+        BadRequestError.new(error['detail'])
+      when 'API Error Unknown'
+        Alula.logger.error response
+        UnknownError.new(error['detail'])
+      when 'Insufficient Scope'
+        InsufficientScopeError.new(error['detail'])
+      else
+        #
+        # RPC errors are identified by jsonrpc in the body.
+        return ProcedureError.new(response) if response.data['jsonrpc']
+        Alula.logger.error response
+        raise NotImplementedError.new("Unable to derive error for #{response.data['errors']}")
+      end
+    end
+  end
+  class UnknownApiError < AlulaError
+  end
+  class RateLimitError < AlulaError
+  end
+  class NotFoundError < AlulaError
+  end
+  class ForbiddenError < AlulaError
+  end
+  class InvalidRequestError < AlulaError
+  end
+  class InvalidTokenError < AlulaError
+  end
+  class InsufficientScopeError < AlulaError
+  end
+  class BadRequestError < AlulaError
+  end
+  class NotConfiguredError < AlulaError
+  end
+  class InvalidFilterFieldError < AlulaError
+  end
+  class InvalidSortFieldError < AlulaError
+  end
+  class InvalidRelationshipError < AlulaError
+  end
+  class InvalidRoleError < AlulaError
+  end
+  class ServerError < AlulaError
+  end
+  class UnknownError < AlulaError
+  end
+  class ProcedureError < AlulaError
+    attr_reader :code, :full_messages
+    def initialize(response)
+      # Take 1 error from the request
+      # TODO: Multiple errors are possible, we probably want to shlep that up
+      error = response.data['error'] || response.data['errors'].first
+      @http_status = response.http_status
+      @raw_response = response
+      @error = error['message']
+      @full_messages = error.dig('data', 'message')&.split(', ') ||
+                        [error['message']]
+      @message = error['message']
+      @code = error['code']
+    end
+    #
+    # Provides interface mirroring to success responses
+    def ok?
+      false
+    end
+  end
+end

data/lib/alula/filter_builder.rb ADDED Viewed

@@ -0,0 +1,271 @@
+require 'json'
+module Alula
+  class FilterBuilder
+    attr_accessor :model_class, :query_interface, :builder
+    def initialize(model_class, query_interface, **args)
+      self.query_interface = query_interface
+      self.model_class = model_class
+      @cache = Hash.new
+    end
+    #
+    # Pseudo-delegator. Merges the current filter into the QueryInterface
+    # then delegates the used method forward
+    instance_eval do
+      %i(list list_all filter_builder limit offset custom_options includes).each do |method|
+        define_method(method) do |*args|
+          query_interface.filter(as_json)
+          query_interface.send(method, *args)
+        end
+      end
+    end
+    #
+    # Takes a hash, one for each key
+    def sort(**args)
+      cleaned_sorts = args.each_pair.each_with_object({}) do |(field, value), collector|
+        field_name = validate_field_sortability! field
+        field_value = validate_sort_value! value
+        collector[field_name] = field_value
+      end
+      query_interface.filter(as_json)
+      query_interface.query_sort(cleaned_sorts)
+    end
+    #
+    # Takes a hash, for each key => value pair returns a strict
+    # hash response for a $where query
+    def where(fields)
+      cleaned = fields.each_pair.each_with_object({}) do |(key, value), collector|
+        field_name = validate_field_filterability! key
+        field_value = simple_value! value
+        collector[field_name] = field_value
+      end
+      update_and_return(cleaned)
+    end
+    #
+    # Takes a hash, for each key => value pair returns a strict
+    # hash response for a $and $where query
+    def and(fields)
+      cleaned = fields.each_pair.each_with_object({}) do |(key, value), collector|
+        field_name = validate_field_filterability! key
+        field_value = simple_value! value
+        collector[field_name] = field_value
+      end
+      update_and_return({ '$and' => cleaned })
+    end
+    #
+    # Define simple comparison operator methods for these query names
+    # Give each method a hash containing fieldName => fieldValue,
+    # Returns a query object in the form of:
+    # {
+    #   "fieldName" => {
+    #     "operator_symbol" => "fieldValue"
+    #   }
+    # }
+    %i(not ne gt gte lt lte like not_like).each do |simple_operator|
+      define_method(simple_operator) do |fields = {}|
+        cleaned = fields.each_pair.each_with_object({}) do |(key, value), collector|
+          field_name = validate_field_filterability! key
+          field_value = simple_value! value
+          collector[field_name] = { "$#{Util.camelize(simple_operator)}" => field_value }
+        end
+        update_and_return cleaned
+      end
+    end
+    #
+    # Dual operation
+    # If given a block it will yield a fresh instance of FilterBuilder, the contents
+    # of which will be stuffed directly into the $or operator.
+    # If given an array, the 1st value is
+    def or(*args, &block)
+      if block_given?
+        new_builder = yield self.class.new(model_class, query_interface)
+        return update_and_return({ '$or' => new_builder.as_json })
+      end
+      value = args[0]
+      fields = args[1..-1]
+      new_values = fields.each_with_object('$or'=>{}) do |key, collector|
+        field_name = validate_field_filterability! key
+        collector['$or'][field_name] = value
+      end
+      update_and_return(new_values)
+    end
+    def or_like(**args)
+      new_values = args.each_pair.each_with_object({}) do |(key, value), collector|
+        field_name = validate_field_filterability! key
+        field_value = simple_value! value
+        collector[field_name] = { '$like' => field_value }
+      end
+      update_and_return('$or' => new_values)
+    end
+    #
+    # Generate a $between query for hash, the values of the hash must be
+    # an array with 2 elements that are JSON-encodable
+    def between(**args)
+      new_values = args.each_pair.each_with_object({}) do |(key, range), collector|
+        field_name = validate_field_filterability! key
+        range_start, range_end = validate_range_value! range, field_name
+        collector[field_name] = { '$between' => [range_start, range_end] }
+      end
+      update_and_return(new_values)
+    end
+    #
+    # Generate a $not_between query for hash, the values of the hash must be
+    # an array with 2 elements that are JSON-encodable
+    def not_between(**args)
+      new_values = args.each_pair.each_with_object({}) do |(key, range), collector|
+        field_name = validate_field_filterability! key
+        range_start, range_end = validate_range_value! range, field_name
+        collector[field_name] = { '$notBetween' => [range_start, range_end] }
+      end
+      update_and_return(new_values)
+    end
+    #
+    # Generate an $in query for hash, the values of the hash must be
+    # an array that is JSON-encodable
+    def in(**args)
+      new_values = args.each_pair.each_with_object({}) do |(key, range), collector|
+        field_name = validate_field_filterability! key
+        values = simple_values! range
+        collector[field_name] = { '$in' => values }
+      end
+      update_and_return(new_values)
+    end
+    #
+    # Generate an $in query for hash, the values of the hash must be
+    # an array that is JSON-encodable
+    def not_in(**args)
+      new_values = args.each_pair.each_with_object({}) do |(key, range), collector|
+        field_name = validate_field_filterability! key
+        values = simple_values! range
+        collector[field_name] = { '$notIn' => values }
+      end
+      update_and_return(new_values)
+    end
+    def as_json
+      @cache
+    end
+    private
+    #
+    # Check the field name against known field names.
+    # Ensure that the field is exists, is filterable
+    # Transform the field name into an API-valid lowerCamelCase
+    # format and return it.
+    def validate_field_filterability!(field_name)
+      underscored = Util.underscore(field_name).to_sym
+      camelized   = Util.camelize(underscored).to_s
+      unless model_class.get_fields.include?(underscored)
+        error = "Field `#{underscored}` does not exist resource `#{model_class}`"
+        raise Alula::InvalidFilterFieldError.new(error)
+      end
+      unless model_class.filterable_fields.include?(underscored)
+        error = "Field `#{underscored}` is not filterable on resource `#{model_class}`"
+        raise Alula::InvalidFilterFieldError.new(error)
+      end
+      camelized
+    end
+    #
+    # Check that a field name is known, and that it is sortable.
+    # Transform the field name into an API-validated lowerCamelCase
+    # TODO: This doesn't belong here, should be on its own include I think
+    def validate_field_sortability!(field_name)
+      underscored = Util.underscore(field_name).to_sym
+      camelized   = Util.camelize(underscored).to_s
+      unless model_class.get_fields.include?(underscored)
+        error = "Field `#{underscored}` does not exist resource `#{model_class}`"
+        raise Alula::InvalidFilterFieldError.new(error)
+      end
+      unless model_class.sortable_fields.include?(underscored)
+        error = "Field `#{underscored}` is not sortable on resource `#{model_class}`"
+        raise Alula::InvalidSortFieldError.new(error)
+      end
+      camelized
+    end
+    def validate_range_value!(range, field_name)
+      unless range.length == 2
+        error = "Provide an array with 2 values to field `#{field_name}` "\
+                "perform a range-based query"
+        raise Alula::InvalidFilterFieldError.new(error)
+      end
+      range[0] = range[0].iso8601 if range[0].respond_to?(:iso8601)
+      range[1] = range[1].iso8601 if range[1].respond_to?(:iso8601)
+      [simple_value!(range[0]), simple_value!(range[1])]
+    end
+    # Ensure a value will be a JSON-encodable value. We don't really care what it is,
+    # but what comes out of JSON serialization is what we'll use.
+    def simple_value!(value)
+      JSON.parse(JSON.fast_generate({ purify: value }))['purify']
+    end
+    def simple_values!(values)
+      values.map{ |v| simple_value!(v) }
+    end
+    def update_cache(new_values)
+      @cache = Util.deep_merge(@cache, new_values)
+      self
+    end
+    def update_and_return(new_values)
+      return new_values if @functional
+      update_cache(new_values)
+    end
+    def validate_sort_value!(value)
+      val = value.to_s.downcase.to_sym
+      unless %i(asc desc).include? val
+        error = "Cannot sort on direction #{val}, please use ASC or DESC only"
+        raise Alula::InvalidSortFieldError.new(error)
+      end
+      val
+    end
+    def update_and_return(new_values)
+      @cache = Util.deep_merge(@cache, new_values)
+      self
+    end
+  end
+end

data/lib/alula/helpers/device_attribute_translations.rb ADDED Viewed

@@ -0,0 +1,68 @@
+module Alula
+  #
+  # Relies on the implementing class having reader properties of `program_id`
+  # and `auto_cfg`. Translates those values into usable strings
+  module DeviceAttributeTranslations
+    PROGRAM_ID_MAP = {
+      32 => 'CONNECT+',
+      35 => 'BAT-FIRE',
+      34 => 'BAT-CONNECT',
+      211 => 'CLARE-D3',
+      4096 => 'CAMERA',
+      783 => 'BAT-LTE',
+      0 => 'IPD-BAT',
+      1 => 'IPD-BAT',
+      2 => 'IPD-BAT',
+      3 => 'IPD-BAT-ZKI',
+      4 => 'IPD-BAT',
+      8 => 'IPD-BAT',
+      6 => 'IPD-ZGW',
+      9 => 'IPD-BAT-U',
+      11 => 'IPD-ZGW',
+      15 => 'IPD-BAT-CDMA',
+      16 => 'IPD-BAT-WIFI',
+      17 => 'IPD-BAT-CDMA-L',
+      18 => 'IPD-MPWC',
+      19 => 'IPD-CAT-CDMA',
+      20 => 'IPD-BAT-CDMA-WIFI',
+      22 => 'IPD-CAT-XT',
+      33 => 'IGM',
+      271 => 'IPD-BAT-CDMA1'
+    }.freeze
+    PANEL_NAME_MAP = {
+      0 => 'Honeywell/Vista',
+      1 => 'Honeywell/Vista+Passive',
+      2 => 'Honeywell/Lynx',
+      3 => 'Honeywell/Lynx+Passive',
+      4 => 'DSC/Depricated',
+      5 => 'GE-Interlogix/Caddx',
+      6 => 'DSC/Alexor',
+      7 => 'DSC/PowerSeries',
+      8 => 'Dialer Capture or Keyswitch',
+      9 => 'GE-Interlogix/Concord',
+      10 => '',
+      11 => 'Gateway',
+      12 => 'GE Simon XT/XTi',
+      13 => 'Cinch',
+      14 => 'Helix',
+      15 => 'Clare D3',
+      19 => 'No Panel',
+    }.freeze
+    def device_name
+      self.class::PROGRAM_ID_MAP[self.program_id] || "Unknown (#{self.program_id})"
+    end
+    #
+    # autoCfg contains multiple pieces of information depending on how you examine it.
+    # Doing a bitwise operation with 0xff takes the last 8 bits,
+    # which is the connected panel ID.
+    # https://ipdatatel.atlassian.net/wiki/spaces/SYS/pages/16482314/auto+cfg
+    def panel_name
+      panel_id = auto_cfg.to_i & 0xff
+      self.class::PANEL_NAME_MAP[panel_id] || "Unknown (#{panel_id})"
+    end
+  end
+end

data/lib/alula/list_object.rb ADDED Viewed

@@ -0,0 +1,64 @@
+module Alula
+  class ListObject
+    include Enumerable
+    attr_reader :items, :type, :meta
+    attr_accessor :rate_limit
+    def initialize list_type
+      @type = list_type
+      @items = []
+    end
+    def length
+      items.length
+    end
+    def each
+      items.each { |i| yield i }
+    end
+    def[] index
+      @items[index]
+    end
+    def first
+      @items.first
+    end
+    def last
+      @items.last
+    end
+    def << item
+      @items << item
+    end
+    def set_meta(meta)
+      @meta = meta
+    end
+    def pagination
+      meta.page
+    end
+    def self.construct_from_response klass, response, opts
+      list = ListObject.new(klass)
+      response.data['data'].each do |item|
+        list << klass.new(item['id']).construct_from(item)
+      end
+      list.set_meta Meta.new(response.data['meta'])
+      list.rate_limit = response.rate_limit
+      list
+    end
+    def self.construct_from_array klass, collection
+      list = ListObject.new(klass)
+      collection.each do |item|
+        list << klass.new(item['id']).construct_from(item)
+      end
+      list
+    end
+  end
+end

data/lib/alula/meta.rb ADDED Viewed

@@ -0,0 +1,16 @@
+module Alula
+  class Meta
+    attr_reader :page, :total, :number, :size
+    def initialize(meta)
+      return unless meta['page']
+      @page = Alula::Pagination.new(meta['page'])
+      # TODO: TJ Deprecate, the meta can hold a lot more than the page
+      @total = @page.total
+      @number = @page.number
+      @size = @page.size
+    end
+  end
+end

data/lib/alula/monkey_patches.rb ADDED Viewed

@@ -0,0 +1,24 @@
+module HTTParty
+  module HashConversions
+    # @param key<Object> The key for the param.
+    # @param value<Object> The value for the param.
+    #
+    # @return <String> This key value pair as a param
+    #
+    # @example normalize_param(:name, "Bob Jones") #=> "name=Bob%20Jones&"
+    def self.normalize_param(key, value)
+      normalized_keys = normalize_keys(key, value)
+      normalized_keys.flatten.each_slice(2).inject('') do |string, (k, v)|
+        # TODO: TJ - Our API needs nil params to be blank, aka '&someParam&'
+        #       and not '&someParam=', otherwise we take that as an empty string.
+        #       Monkey patch to get around this problem.
+        if v.nil?
+          string + "#{ERB::Util.url_encode(k)}&"
+        else
+          string + "#{ERB::Util.url_encode(k)}=#{ERB::Util.url_encode(v.to_s)}&"
+        end
+      end
+    end
+  end
+end