alula-ruby 2.6.3 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9018c7bf17b64dc46d9ecbce83df2fb8fa36313cc2baa70216c806e508ad8ebe
-  data.tar.gz: 5552587d5c7d441b3fb48f7740c8c2e55f7e20b3e964f17465ba30913ddb7931
+  metadata.gz: 41fa026d04be1c00a48b82beacd3d38f4e20ed611960477c8f86741d068f4d6e
+  data.tar.gz: 64f2dd9e84eb4b0afe9ce4a6e9eeae2e9f236999437d9f8a5bd120eab7ffecc3
 SHA512:
-  metadata.gz: c8ddefb2c1f5094d244b0106cdfa28b7e6b7eea2e74059565d1163b3579967e3e8923b298efdeae1000cac9182ab00b916f396262f50fe766060fa0523fa2d81
-  data.tar.gz: c1ff8064e6355d95f575dc779e42729e68327a02ae16606278b20c29b69ee36dea81e7f510113557ea7f94cd1cff582942d606caeefa841a8199354fd9c8af4f
+  metadata.gz: 70be4d9af3d5720c063710e0c76499d3aeff541a8ec5a1739f65b913cd57b3a3339cb5ec038650ecb144e77e36938cc889c7564d204ba2ec12039a867c6aa2ef
+  data.tar.gz: 637c4322fae7e3734f5ff382413aed172591c80841b3f4236d9c1b98cc72e6ab0c505517b870ccf2bf04b5209990b4645d03072bbce26f61c9ec162cb142e3d3

data/VERSION.md

@@ -2,6 +2,7 @@
 
 | Version | Date        | Description                                                                 |
 | ------- | ------------| --------------------------------------------------------------------------- |
+| v2.7.0  | 2025-02-05  | Add DCP client |
 | v2.6.3  | 2025-01-30  | Add alula_controllable_sim field to device |
 | v2.6.2  | 2025-01-30  | Fix Core API Docker container setup |
 | v2.6.1  | 2025-01-14  | Add ezviz? method to device |

data/bin/console

@@ -47,5 +47,4 @@ def setup_client(token)
     c.video_api_key = ENV['VIDEO_API_DOMAIN']
   end
 end
-
 IRB.start(__FILE__)

data/lib/alula/dcp/error_handler.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    # DCP Error Handler
+    module ErrorHandler
+      def handle_errors(response)
+        case response.http_status
+        when 300..399
+          # Should never see a 300-range response code
+          raise Alula::UnknownError,
+                "The Alula-Ruby gem encountered a response code of #{response.http_status}, that should not happen"
+        when 500..599
+          # Server errors, malformed data, etc
+          AlulaError.for_response(response)
+        when 400..499
+          # Validation errors usually
+          model_errors = Util.model_errors_from_dcp_response(response)
+          return AlulaError.for_response(response) unless model_errors
+
+          annotate_errors(model_errors)
+          false
+        else
+          raise Alula::UnknownError, "Unknown HTTP response code, aborting. Code: #{response.http_status}"
+        end
+      end
+    end
+  end
+end

data/lib/alula/dcp/list_object.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    # Used to create a new list of DCP objects
+    class ListObject
+      include Enumerable
+
+      attr_reader :items, :type
+      attr_accessor :rate_limit
+
+      def initialize(list_type)
+        @type = list_type
+        @items = []
+      end
+
+      def length
+        items.length
+      end
+
+      def each(&block)
+        items.each { |item| block.call(item) }
+      end
+
+      def[](index)
+        @items[index]
+      end
+
+      def first
+        @items.first
+      end
+
+      def last
+        @items.last
+      end
+
+      def <<(item)
+        @items << item
+      end
+
+      def self.construct_from_response(device_id, klass, response, _opts)
+        # TODO: add pagination support if/when DCP supports it
+        list = ListObject.new(klass)
+        response.data.each do |sub_klass_string, items|
+          # if it's a real class, create an instance of it
+          # otherwise, log a warning and skip it
+          ruby_sub_klass_string = Util.upper_camelcase_from_camelcase(sub_klass_string)
+          sub_klass_name = "#{klass}::#{ruby_sub_klass_string}"
+          sub_klass = klass.const_defined?(ruby_sub_klass_string, false) ? Object.const_get(sub_klass_name) : nil
+          if sub_klass.nil?
+            Alula.logger.warn("No class found for #{sub_klass_name}")
+            next
+          end
+
+          sub_klass_list = []
+          items.each do |item|
+            sub_klass_list << sub_klass.new(device_id, item['index'], item)
+          end
+          list << sub_klass_list
+          # define getter method for each sub_klass
+          ruby_method = Util.underscore(sub_klass_string)
+          list.define_singleton_method(ruby_method) do
+            sub_klass_list
+          end
+        end
+        list.rate_limit = response.rate_limit
+
+        list
+      end
+    end
+  end
+end

data/lib/alula/dcp/meta.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    # DCP Record Meta
+    class Meta
+      attr_reader :last_recv_result, :last_recv_nak_reason, :last_recv_time, :recv_needed,
+                  :last_write_time, :last_write_result, :last_write_nak_reason
+
+      def initialize(data)
+        data.each do |key, value|
+          ruby_key = Util.underscore(key)
+          instance_variable_set("@#{ruby_key}", value)
+        end
+      end
+    end
+  end
+end

data/lib/alula/dcp/resource_attributes.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Alula
+  module Dcp
+    module ResourceAttributes
+      def self.extended(base)
+        base.class_eval do
+          @resource_path = nil
+          @type = nil
+          @http_methods = []
+          @fields = {}
+        end
+        base.include(InstanceMethods)
+      end
+
+      #
+      # Class methods for defining how fields and types work
+      # NOTE: We're not using real getters and setters here. I want the method signature
+      #       to match how most other Ruby class configuration is done, and that is with
+      #       simple methods that take params.
+      def resource_path(name)
+        @resource_path = name
+      end
+
+      def get_resource_path(index = nil)
+        return "#{@resource_path}/#{index}" if index
+
+        @resource_path
+      end
+
+      def type(type)
+        @type = type
+      end
+
+      def get_type
+        @type
+      end
+
+      def http_methods(methods)
+        @http_methods = methods
+      end
+
+      def get_http_methods
+        @http_methods
+      end
+
+      #
+      # Memoizes field names and options
+      def field(field_name, **opts)
+        @fields ||= {}
+        @fields[field_name] = opts
+      end
+
+      def get_fields
+        @fields
+      end
+
+      def date_fields
+        @date_fields ||=
+          get_fields.each_pair.each_with_object([]) do |(field_name, opts), collector|
+            collector << field_name if opts[:type].to_sym == :date
+          end
+      end
+
+      def filterable_fields
+        get_fields.each_pair.each_with_object([]) do |(field_name, opts), collector|
+          collector << field_name if opts[:filterable] == true
+        end
+      end
+
+      def sortable_fields
+        get_fields.each_pair.each_with_object([]) do |(field_name, opts), collector|
+          collector << field_name if opts[:sortable] == true
+        end
+      end
+
+      def field_names
+        get_fields.keys
+      end
+
+      def param_key
+        name.gsub('::', '_').downcase
+      end
+
+      private
+
+      def metaclass
+        class << self
+          self
+        end
+      end
+
+      def field_patchable?(opts, record_persisted)
+        user_role = Alula::Client.config.role
+
+        # different permission arrays are used for updates vs creates
+        perm_key = record_persisted == true ? :patchable_by : :creatable_by
+
+        return true if opts[perm_key].include? :all
+
+        opts[perm_key].include? user_role
+      end
+
+      #
+      # Extensions to allow instances to get at their class config, either raw or
+      # reduced to a useable format for a specific task.
+      module InstanceMethods
+        # Instance method extensions
+        def type(arg)
+          self.class.type(arg)
+        end
+
+        def get_type
+          self.class.get_type
+        end
+
+        def fields
+          self.class.get_fields
+        end
+
+        def field_names
+          self.class.field_names
+        end
+
+        def persisted?
+          return false unless respond_to?(:index)
+
+          !index.nil?
+        end
+
+        #
+        # Return the names of each field configured as a date type
+        def date_fields
+          self.class.date_fields
+        end
+
+        def to_key
+          key = respond_to?(:index) && index
+          key ? [key] : nil
+        end
+      end
+    end
+
+    class ObjectField
+      extend ResourceAttributes
+
+      # Assume properties is camel case
+      def initialize(parent_field, properties = nil)
+        @parent_field = parent_field
+        return unless properties
+
+        valid_fields = self.class.get_fields
+        properties.dup.each do |key, value|
+          ruby_key = Alula::Util.underscore(key.to_s)
+          next unless valid_fields.key?(ruby_key.to_sym)
+
+          instance_variable_set("@#{ruby_key}", value)
+          define_singleton_method(ruby_key) { instance_variable_get("@#{ruby_key}") }
+          define_singleton_method("#{ruby_key}=") { |val| instance_variable_set("@#{ruby_key}", val) }
+        end
+      end
+
+      def as_json
+        field_names.each_with_object({}) do |ruby_key, obj|
+          key = Util.camelize(ruby_key)
+          val = respond_to?(ruby_key) ? send(ruby_key) : nil
+          next if val.nil?
+
+          obj[key] = parse_value(val, ruby_key)
+        end
+      end
+
+      private
+
+      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
+    end
+  end
+end

data/lib/alula/dcp_operations/delete.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# TODO: Add real delete implementation when DCP supports it
+module Alula
+  module DcpOperations
+    module Delete
+      def self.extended(base)
+        base.include(InstanceMethods)
+      end
+
+      module InstanceMethods
+        include Alula::Dcp::ErrorHandler
+        def delete
+          payload = {
+            data: {
+              id: id,
+              attributes: as_blank_patchable_json
+            }
+          }
+          response = Alula::Client.request(:patch, resource_url, payload)
+
+          return true if response.ok?
+
+          handle_errors(response)
+        end
+      end
+    end
+  end
+end

data/lib/alula/dcp_operations/delete_staged.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# TODO: Add real delete implementation when DCP supports it
+# technically it does support delete staged at the moment
+# but I would like to wait for the real delete.rb implementation to be added first
+module Alula
+  module DcpOperations
+    module DeleteStaged
+      def self.extended(base)
+        base.include(InstanceMethods)
+      end
+
+      module InstanceMethods
+        include Alula::Dcp::ErrorHandler
+        def delete_staged
+          response = Alula::Client.request(:patch, "#{resource_url}/staged")
+
+          return true if response.ok?
+
+          handle_errors(response)
+        end
+      end
+    end
+  end
+end

data/lib/alula/dcp_operations/list.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Alula
+  module DcpOperations
+    # Allows for the creation of a list of objects
+    module List
+      def self.extended(base)
+        base.include(InstanceMethods)
+      end
+
+      def method_missing(method, *args, &block)
+        QueryInterface.new(self).send(method, *args, &block)
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        QueryInterface.new(self).respond_to?(method, include_private)
+      end
+
+      def list(device_id, filters = {}, opts = {})
+        response = Alula::Client.request(:get, resource_url(device_id), filters, opts)
+        if response.ok?
+          Alula::Dcp::ListObject.construct_from_response(device_id, self, response, opts)
+        else
+          error_class = AlulaError.for_response(response)
+          raise error_class
+        end
+      end
+
+      # Instance methods
+      module InstanceMethods
+      end
+    end
+  end
+end

data/lib/alula/dcp_operations/request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Alula
+  module DcpOperations
+    # Allows for retrieving a single object by index
+    module Request
+      def self.extended(base)
+        base.include(InstanceMethods)
+      end
+
+      # Load a single model by Index
+      def retrieve(device_id, index, built_filters = {})
+        response = Alula::Client.request(:get, resource_url(device_id, index), built_filters, {})
+        if response.ok?
+          item = new(device_id, index, response.data)
+          item.rate_limit = response.rate_limit
+          item
+        else
+          error_class = AlulaError.for_response(response)
+          raise error_class
+        end
+      end
+
+      # Instance methods
+      module InstanceMethods
+        def request(method, url, params, opts)
+          Alula::Client.request(method, url, params, opts)
+        end
+      end
+    end
+  end
+end

data/lib/alula/dcp_operations/save.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Alula
+  module DcpOperations
+    # Module for saving a model
+    module Save
+      def self.extended(base)
+        base.include(InstanceMethods)
+      end
+
+      # Instance methods for saving a model
+      module InstanceMethods
+        include Alula::Dcp::ErrorHandler
+        def save
+          payload = as_patchable_json
+          response = Alula::Client.request(:patch, "#{resource_url}/staged", payload, {})
+
+          if response.ok?
+            construct_from(device_id, index, response.data)
+            return true
+          end
+          handle_errors(response)
+        end
+
+        def save!
+          save || raise(ValidationError, errors)
+        end
+
+        def create
+          payload = {
+            data: as_patchable_json
+          }
+
+          response = Alula::Client.request(:post, self.class.resource_url, payload, {})
+
+          if response.ok?
+            index = response.data['index']
+            construct_from(device_id, index, response.data)
+            return true
+          end
+
+          handle_errors(response)
+        end
+      end
+    end
+  end
+end