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

alula-ruby 0.50.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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