alula-ruby 2.6.3 → 2.7.0

data/lib/alula/dcp_resource.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Alula
+  # Parent class for all DCP objects
+  class DcpResource
+    attr_accessor :device_id, :index, :raw_data, :meta, :errors, :rate_limit, :dirty_attributes, :value, :staged
+
+    def self.class_name
+      name.split('::')[-1]
+    end
+
+    def initialize(device_id, index = nil, attributes = {})
+      @raw_data = {}
+      @dirty_attributes = {}
+      @errors = ModelErrors.new(self.class)
+      construct_from(device_id, index, attributes)
+    end
+
+    def clone
+      self.class.new(@device_id, nil, @raw_data)
+    end
+
+    #
+    # Construct a new resource, ready to receive attributes, with
+    # empty values for all attrs.
+    # Useful for making New resources
+    def self.build(device_id)
+      fields = get_fields.keys.map { |k| Util.camelize(k) }
+      empty_shell = fields.each_with_object({}) { |f, obj| obj[f] = nil }
+      new(device_id, nil, empty_shell)
+    end
+
+    def construct_from(device_id, index, json_object)
+      raise ArgumentError, 'device_id is required' if device_id.empty?
+
+      @raw_data = json_object.dup
+      assign_meta_value_staged(json_object)
+      self.index = index
+      self.device_id = device_id
+
+      @errors = ModelErrors.new(self.class)
+
+      self
+    end
+
+    #
+    # Take a hash of attributes and apply them to the model
+    def apply_attributes(attributes)
+      attributes.each do |key, value|
+        next unless fields.include?(key)
+
+        @dirty_attributes[key] = value
+      end
+    end
+
+    def reconstruct_from(device_id, index, json_object)
+      construct_from(device_id, index, json_object)
+    end
+
+    def errors?
+      @errors.any?
+    end
+
+    def refresh
+      response = Alula::Client.request(:get, resource_url, {}, {})
+      if response.ok?
+        model = construct_from(device_id, index, response.data)
+        model.rate_limit = response.rate_limit
+        model
+      else
+        error_class = AlulaError.for_response(response)
+        raise error_class
+      end
+    end
+
+    #
+    # Fetch known attributes out of the object, collected into a Hash in camelCase format
+    # Intended for eventually making its way back up to the API
+    def as_json
+      field_names.each_with_object({}) do |ruby_key, obj|
+        key = Util.camelize(ruby_key)
+        val = find_value(ruby_key)
+
+        next if val.nil?
+
+        obj[key] = if val.is_a? Array
+                     val.map { |v| parse_value(v, ruby_key) }
+                   elsif val.is_a? Alula::Dcp::ObjectField
+                     val.as_json
+                   else
+                     parse_value(val, ruby_key)
+                   end
+      end
+    end
+
+    def find_value(key)
+      # prioritize dirty attributes, then staged, then value
+      # ideally we should use only dirty attributes, done by executing .apply_attributes
+      return @dirty_attributes[key] if @dirty_attributes.include?(key)
+      return @staged.send(key) if @staged.respond_to?(key)
+
+      @value.send(key) if @value.respond_to?(key)
+    end
+
+    #
+    # Reduce as_json to a set that can be updated
+    def as_patchable_json
+      values = as_json.each_pair.each_with_object({}) do |(key, val), collector|
+        collector[key] = val
+      end
+
+      values.reject { |k, _v| %w[index version].include? k } # blacklist index and version
+    end
+
+    def annotate_errors(model_errors)
+      @errors = ModelErrors.new(self.class)
+      model_errors.each_pair do |field_name, error|
+        errors.add(field_name, error)
+      end
+    end
+
+    #
+    # Return an instance of QueryEngine annotated with the correct model attributes
+    def filter_builder
+      Alula::FilterBuilder.new(self.class)
+    end
+    alias fb filter_builder
+
+    def model_name
+      self.class
+    end
+
+    # Class for holding model errors
+    class ModelErrors
+      include Enumerable
+
+      def initialize(model_class)
+        @model_class = model_class
+        @details = {}
+      end
+
+      def each
+        @details.each do |field, error|
+          yield({ field => error })
+        end
+      end
+
+      def any?
+        @details.any?
+      end
+
+      def add(field_name, error_message)
+        @details[field_name] = error_message
+      end
+
+      def [](field_name)
+        @details[field_name.to_sym]
+      end
+
+      def full_messages
+        @details.map { |field, error| "#{field}: #{error}" }
+      end
+
+      def full_messages_for(attribute_name)
+        return nil unless @details[attribute_name.to_sym].present?
+
+        "#{attribute_name}: #{@details[attribute_name.to_sym]}"
+      end
+    end
+
+    private
+
+    def assign_meta_value_staged(json_object)
+      @meta = Alula::Dcp::Meta.new(json_object['meta']) unless empty_value?(json_object['meta'])
+      @value = convert_to_ruby_object(json_object['value'])
+      @staged = convert_to_ruby_object(json_object['staged'])
+    end
+
+    def convert_to_ruby_object(object)
+      return nil if object.nil?
+
+      fields.each_pair.each_with_object({}) do |(field_name, opts), obj|
+        value = object[Util.camelize(field_name.to_s)]
+        if value.nil?
+          # we still need to define the method, even if it's nil
+          obj[field_name] = nil
+          obj.define_singleton_method(field_name) { obj[field_name] }
+          next
+        end
+
+        obj[field_name] =
+          if opts[:type] == :date && ![nil, ''].include?(value)
+            begin
+              DateTime.parse(value)
+            rescue ArgumentError
+              value
+            end
+          elsif opts[:type] == :object && opts[:use] && !value.nil? && value.respond_to?(:each)
+            opts[:use].new(field_name, value)
+          elsif opts[:type] == :array && opts[:use] && !value.nil? && value.respond_to?(:each)
+            # Array of objects, each object is a new instance of the use class
+            value.each_with_object([]) do |item, collector|
+              collector << opts[:use].new(field_name, item)
+            end
+          elsif opts[:type] == :boolean
+            [true, 'true', 1, '1'].include? value
+          elsif opts[:type] == :number
+            value&.to_i
+          else
+            value
+          end
+        obj.define_singleton_method(field_name) { obj[field_name] }
+      end
+    end
+
+    def parse_value(value, ruby_key)
+      if date_fields.include?(ruby_key) && ![nil, ''].include?(value)
+        extract_date(value)
+      elsif value.is_a? Alula::Dcp::ObjectField
+        value.as_json
+      else
+        value
+      end
+    end
+
+    def extract_date(value)
+      if value.respond_to? :strftime
+        value.strftime('%Y-%m-%dT%H:%M:%S.%L%z')
+      else
+        value.to_s
+      end
+    end
+
+    def empty_value?(value)
+      [nil, ''].include?(value)
+    end
+  end
+end

data/lib/alula/errors.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module Alula
   class AlulaError < StandardError
     attr_reader :http_status, :raw_response, :error, :message
+
     def initialize(error)
       if error.class == String
         @message = error
@@ -24,9 +27,12 @@ module Alula
       elsif !response.data['errors'].nil? && !response.data['errors'].empty?
         self.errors_for_response(response)
 
+      elsif !response.data['message'].nil?
+        self.error_for_response(response)
+
       elsif response.data.match(/^<!DOCTYPE html>/)
         self.critical_error_for_response(response.data.scan(/<pre>(.*)<\/pre>/))
-      
+
       elsif response.data.match(/502 Bad Gateway/)
         self.gateway_error_for_response(response.data.scan(/502 Bad Gateway/))
       else
@@ -34,7 +40,6 @@ module Alula
         Alula.logger.error message
         raise UnknownApiError.new(message)
       end
-
     rescue NoMethodError
       message = "Unable to derive error from response: #{response.inspect}"
       Alula.logger.error message
@@ -66,6 +71,10 @@ module Alula
       when 'server_error'
         Alula.logger.error response
         ServerError.new(response)
+      when 'Bad Request'
+        BadRequestError.new(response)
+      when 'Not Found'
+        NotFoundError.new(response)
       else
         #
         # RPC errors are identified by jsonrpc in the body.
@@ -77,7 +86,8 @@ module Alula
         # Here we have some errors that are actually known but at least one of them is not properly formatted by the API
         message = response.data.dig('error', 'data', 'msg') ||
                   response.data.dig('error', 'data', 'message') ||
-                  response.data.dig('error', 'description')
+                  response.data.dig('error', 'description') ||
+                  response.data['message']
         case message
         when 'dealer does not exist'
           NotFoundError.new(message)
@@ -199,14 +209,14 @@ module Alula
       @http_status = response.http_status
       @raw_response = response
       @error = error['message']
-      @full_messages = error.dig('data', 'message')&.split(', ') || 
-                        [error['message']]
+      @full_messages = error.dig('data', 'message')&.split(', ') ||
+                       [error['message']]
       @message = error['message']
       @code = error['code']
     end
 
     #
-    # Provides interface mirroring to success responses 
+    # Provides interface mirroring to success responses
     def ok?
       false
     end

data/lib/alula/helpers/device_helpers/program_id_helper.rb

@@ -76,6 +76,10 @@ module Alula
       end
 
       def alder_wtp?
+        [38, 44].include?(program_id)
+      end
+
+      def alder_wtp_01?
         program_id == 38
       end
 

data/lib/alula/resource_attributes.rb

@@ -52,11 +52,11 @@ module Alula
       @fields[field_name] = opts
 
       self.instance_eval do
-        jsonKey = Util.camelize(field_name)
+        json_key = Util.camelize(field_name)
 
         # Reader method for attribute
         define_method(field_name) do
-          value = @values[jsonKey]
+          value = @values[json_key]
 
           if opts[:type] == :date && ![nil, ''].include?(value)
             begin
@@ -72,7 +72,7 @@ module Alula
             # API sends a camelCase string; provide symbol to Client
             value ? Util.underscore(value).to_sym : nil
           elsif opts[:hex_convert_required] == true
-            Util.convert_hex_crc?(self.program_id) ? value.to_s(16) : value
+            Util.convert_hex_crc?(program_id) ? value.to_s(16) : value
           elsif opts[:type] == :number
             value&.to_i
           else
@@ -96,10 +96,10 @@ module Alula
           end
 
           # Mark the attribute as dirty if the new value is different
-          mark_dirty(field_name, @values[jsonKey], new_value)
+          mark_dirty(field_name, @values[json_key], new_value)
           #
           # Assign the new value (always assigned even if a duplicate)
-          @values[jsonKey] = new_value
+          @values[json_key] = new_value
         end
       end
     end

data/lib/alula/resources/dcp/base_resource.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    # Base class for DCP resources
+    class BaseResource < Alula::DcpResource
+      class << self
+        def api_name(name = nil)
+          if name
+            @api_name = name
+          elsif @api_name
+            @api_name
+          else
+            superclass.api_name
+          end
+        end
+
+        # Infer resource name from classname if not provided
+        def resource_name(name = nil)
+          if name
+            @resource_name = name
+          elsif @resource_name
+            @resource_name
+          else
+            @resource_name = self.name.split('::').last.downcase.to_sym
+          end
+        end
+
+        def resource_url(device_id, index = nil)
+          base_url = "/#{api_name}/v2/helix/#{device_id}/#{resource_name}"
+          index ? "#{base_url}/#{index}" : base_url
+        end
+      end
+
+      api_name :dcp
+
+      # Instance method
+      def resource_url(device_id = self.device_id, index = self.index)
+        "/#{self.class.api_name}/v2/helix/#{device_id}/#{self.class.resource_name}/#{index}"
+      end
+    end
+  end
+end

data/lib/alula/resources/dcp/config/synchronize.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    class Config
+      # Synchronize DCP configuration
+      class Synchronize < Alula::SingletonDcpCommandResource
+        extend Alula::Dcp::ResourceAttributes
+
+        resource_path 'config/synchronize'
+
+        field :alarm_types_supported, type: :boolean
+        field :arming_level_options_by_arming_level, type: :boolean
+        field :bus_modules, type: :boolean
+        field :comm_data, type: :boolean
+        field :custom_zone_profiles, type: :boolean
+        field :fob_data, type: :boolean
+        field :local_scene_actions, type: :boolean
+        field :local_scene_names, type: :boolean
+        field :local_scene_triggers, type: :boolean
+        field :local_scenes, type: :boolean
+        field :misc_nv_data, type: :boolean
+        field :wireless_peripherals, type: :boolean
+        field :mobile_device_names, type: :boolean
+        field :mobile_device_settings, type: :boolean
+        field :outputs, type: :boolean
+        field :panel_options, type: :boolean
+        field :partitions, type: :boolean
+        field :pin_pad_data, type: :boolean
+        field :pinger_fob_data, type: :boolean
+        field :siren_data, type: :boolean
+        field :time_schedules, type: :boolean
+        field :timers, type: :boolean
+        field :user_mapping, type: :boolean
+        field :users_data, type: :boolean
+        field :zone_data, type: :boolean
+        field :zwave_device_names, type: :boolean
+
+        def self.call(device_id:, payload:)
+          request(
+            device_id: device_id,
+            http_method: :post,
+            payload: payload
+          )
+        end
+
+        def self.payload_required?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/alula/resources/dcp/config.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    class Config
+    end
+  end
+end

data/lib/alula/resources/dcp/users_data/installer_pin.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    class UsersData
+      # Panel User Resource
+      class InstallerPin < Alula::Dcp::BaseResource
+        extend Alula::Dcp::ResourceAttributes
+        extend Alula::DcpOperations::Request
+        extend Alula::DcpOperations::Save
+        extend Alula::DcpOperations::Delete
+        extend Alula::DcpOperations::DeleteStaged
+
+        resource_name 'config/usersData/installerPin'
+
+        field :primitive,
+              type: :string
+      end
+    end
+  end
+end

data/lib/alula/resources/dcp/users_data/user.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    class UsersData
+      # Panel User Resource
+      class User < Alula::Dcp::BaseResource
+        extend Alula::Dcp::ResourceAttributes
+        extend Alula::DcpOperations::Request
+        extend Alula::DcpOperations::Save
+        extend Alula::DcpOperations::Delete
+        extend Alula::DcpOperations::DeleteStaged
+
+        resource_name 'config/usersData/user'
+
+        # Partition class to be used as an array field on the User class
+        class Partition < Alula::Dcp::ObjectField
+          field :assigned,
+                type: :boolean
+
+          field :bypass_zones,
+                type: :boolean
+
+          field :manage_users,
+                type: :boolean
+
+          field :system_test,
+                type: :boolean
+
+          field :view_history,
+                type: :boolean
+
+          field :control_outputs,
+                type: :boolean
+
+          field :manage_scenes,
+                type: :boolean
+
+          field :manage_zwave_devices,
+                type: :boolean
+
+          field :silence_trouble_beeps,
+                type: :boolean
+
+          field :zone_sensor_reset,
+                type: :boolean
+
+          field :master_user,
+                type: :boolean
+
+          field :confirm_alarms,
+                type: :boolean
+
+          field :control_chime_mode,
+                type: :boolean
+
+          field :level1,
+                type: :boolean
+
+          field :level2,
+                type: :boolean
+
+          field :level3,
+                type: :boolean
+
+          field :level4,
+                type: :boolean
+
+          field :level5,
+                type: :boolean
+
+          field :level6,
+                type: :boolean
+
+          field :level7,
+                type: :boolean
+
+          field :level8,
+                type: :boolean
+        end
+
+        field :display_name,
+              type: :string
+
+        field :user_fob_number,
+              type: :number
+
+        field :user_pin,
+              type: :string
+
+        field :partitions,
+              type: :array,
+              use: Partition
+
+        field :version,
+              type: :number
+      end
+    end
+  end
+end

data/lib/alula/resources/dcp/users_data.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    # Main class for UsersData
+    # Subclasses: UsersData::User, UsersData::DuressPin, UsersData::InstallerPin, UsersData::AccessCodeUserMapping
+    class UsersData < Alula::Dcp::BaseResource
+      extend Alula::DcpOperations::List
+
+      resource_name 'config/usersData'
+    end
+  end
+end

data/lib/alula/singleton_dcp_command_resource.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Alula
+  # Base class for DCP command resources
+  class SingletonDcpCommandResource
+    attr_accessor :device_id, :values
+
+    BASE_PATH = '/dcp/v2/helix'
+
+    def initialize(device_id, attributes = nil)
+      @values = attributes || {}
+      construct_new_resource(device_id)
+    end
+
+    def model_name
+      self.class
+    end
+
+    def self.request(device_id:, http_method:, path: get_resource_path, payload: {}, opts: {})
+      if self == Alula::SingletonDcpCommandResource
+        raise NotImplementedError,
+              'Alula::SingletonDcpCommandResource is an abstract class and cannot be instantiated.' \
+              ' You should perform actions on its subclasses (Synchronize, etc.)'
+      end
+      if payload.empty? && payload_required?
+        raise ArgumentError, 'Payload is empty. This will result in a useless request.'
+      end
+
+      path = "#{BASE_PATH}/#{device_id}/#{path}"
+      payload = payload_to_camelcase(payload)
+      response = Alula::Client.request(http_method, path, payload, opts)
+
+      unless response.ok?
+        error = Alula::AlulaError.for_response(response)
+
+        #
+        # Some error classifications are critical and should be raised for visibility
+        # These errors do not contain meaningful data that an end-user can use to correct
+        # the error.
+        raise error if [Alula::RateLimitError, Alula::BadRequestError, Alula::ForbiddenError,
+                        Alula::UnknownError, Alula::InsufficientScopeError].include?(error.class)
+
+        return error
+      end
+
+      new(device_id, response.data)
+    end
+
+    def construct_new_resource(device_id)
+      self.device_id = device_id
+      instance_eval do
+        fields.each_key do |field|
+          camel_key = Util.camelize(field)
+          define_singleton_method(field) do
+            if @values.key?(camel_key)
+              @values[camel_key]
+            else
+              @values[field]
+            end
+          end
+          define_singleton_method("#{field}=") do |value|
+            if @values.key?(camel_key)
+              @values[camel_key] = value
+            else
+              @values[field] = value
+            end
+          end
+        end
+      end
+    end
+
+    def apply_attributes(attributes)
+      attributes.each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    def call
+      self.class.call(device_id: device_id, payload: @values)
+    end
+
+    def self.payload_to_camelcase(payload)
+      # recursively convert all keys to camelcase
+      payload.each_with_object({}) do |(key, value), hash|
+        hash[Util.camelize(key)] = if value.is_a?(Array)
+                                     value.map { |v| v.is_a?(Hash) ? payload_to_camelcase(v) : v }
+                                   else
+                                     value.is_a?(Hash) ? payload_to_camelcase(value) : value
+                                   end
+      end
+    end
+
+    def self.payload_required?
+      # return false unless the method is overridden
+      return false unless method_defined?(:payload_required?)
+
+      payload_required?
+    end
+  end
+end