ruby-miradore 4.4.2 → 4.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fa7bea04e363a3b0d7b478a83273c750f7e8b51d1accdc9bfc6f2e6a2363bed
-  data.tar.gz: 1ff8e591ee1e65adb8cb7e29e34be5a376ef179b0cebe699b5ea68c42d2125a9
+  metadata.gz: 6f593a23d0e8d61e532551e6d9a6937f1bcd6620cd5c63d5e368abe1a7233210
+  data.tar.gz: 5fd985ccdae20fe0f1dafb5f7e33dc4662b9f80c25e6150cace217d176453b88
 SHA512:
-  metadata.gz: fae95e829257c215c9c115cf292bca0a11b1adb64f7c84079d23912cc1115a0744bf1695eab937129595217e3b949b6752170dba8300e1fe3cb391a1fdb1cd0c
-  data.tar.gz: ae53294cb3b31b5c70db09e6545c946a36baa0476cb1e2a00a169c8acf04bc96353eefb7ba54462c4bbd28705dff349b7f07ff778143b13744a0beb63086dc4e
+  metadata.gz: 3e7f2e1c73b7932a599d7de0e8a7d8fd76c73f293044bbd77aaccc3127a942b4d597d9ec16383008998bb161dd7a658fde32b8339be524913f0a7c5e55457e2a
+  data.tar.gz: 4cbb4045fd90ff8fa58be37ba2df92861c7572d0a2705afadb8ebf58f8eb9c4da81e52303f0f0695b1dcb9aa579fff43889989a94c0effb3f8624907fbe9db97

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-miradore (4.4.2)
+    ruby-miradore (4.4.4)
       activesupport (~> 7.0)
       builder (~> 3.1)
       crack (~> 0.4)

data/lib/ruby/miradore/version.rb

@@ -2,6 +2,6 @@
 
 module Ruby
   module Miradore
-    VERSION = '4.4.2'
+    VERSION = '4.4.4'
   end
 end

data/lib/ruby/miradore.rb

@@ -3,13 +3,32 @@
 require_relative 'miradore/version'
 require 'active_support/isolated_execution_state'
 require 'active_support/core_ext/hash/conversions'
+require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/module/attribute_accessors'
 require 'httparty'
 require 'json'
 require 'crack/xml'
 require 'finest/builder'
 
+# Ruby::Miradore module
+# The response will be an array of Ruby::Miradore::Device objects with the attributes of the device.
+# Ruby::Miradore::Device object is an open struct so you can access the attributes using the dot notation and any 
+# missing method will return +nil+.
+# @example Usage example for Ruby::Miradore::Device
+#  device = Ruby::Miradore::Device.new(subdomain: 'testXX', auth: '1xxxxxx')
+#  device.all(filter: 'ID eq 37')
 module Ruby
+  # Ruby::Miradore module
+  # Miradore has two main API versions, v1 and v2.
+  # The v1 version is used to retrieve devices based on filters and the v2 version is used to retrieve a device based on the ID and
+  # perform actions on the device.
+  # The v1 version works with XML and it's used to perform CRUD operations on users, groups, categories, and devices.
+  # The v2 version works with JSON and it's used to perform actions on devices.
+  # @see https://www.miradore.com/knowledge/integrations/programmers-guide-to-api-v1/
+  # @see https://www.miradore.com/knowledge/integrations/miradore-api-v2/
+  # @example Usage example for Ruby::Miradore
+  #  Ruby::Miradore::Device.new(subdomain: 'subdomain', auth: 'api_token').all(attribute: 'InvDevice.*,InvOS.*,InvStorage.*,Security.*,Location.*,Enrollment.*,User.*')
+  #
   module Miradore
 
     mattr_accessor :url, default: {
@@ -34,6 +53,10 @@ module Ruby
       yield(self)
     end
 
+    # Ruby::Miradore::Request class
+    # This class is the base class for all the requests and implement the CRUD methods towards the API v1 version.
+    # The class is using the +HTTParty+ gem to perform the requests and the Finest::Builder gem to transform the XML response into
+    # an array of Ruby::Miradore::Request objects.
     class Request
       include Finest::Builder
       include HTTParty
@@ -41,10 +64,13 @@ module Ruby
 
       attr_writer :subdomain, :auth, :json
 
+      # @param args [Hash] The arguments to be passed to the API blank hash by default
+      # @example Usage example for Ruby::Miradore::Request without arguments, it will use the default values
+      #  Ruby::Miradore::Request.new.all
       def initialize(args = {})
         super args
-        @subdomain ||= args[:subdomain]
-        @auth ||= args[:auth]
+        @subdomain ||= args.with_indifferent_access[:subdomain]
+        @auth ||= args.with_indifferent_access[:auth]
         @json ||= args.to_json
         remove_instance_variable(:@subdomain) if @subdomain.nil?
         remove_instance_variable(:@auth) if @auth.nil?
@@ -55,7 +81,7 @@ module Ruby
       # The version would be determined based on the superclass name.
       # If the superclass is Request the GET will call simple_v1 which will require the item which is class name.
       # otherwise will call to retrieve devices based on filters.
-      #
+      # @param args [Hash] The arguments to be passed to the API
       def all(args = {})
         transform(
           Crack::XML.parse(
@@ -76,12 +102,14 @@ module Ruby
         @json
       end
 
+      # Constructs the URL adding parameters to the URL based on the arguments passed and using the API v1 format.
+      # Transforms the +body+ argument into XML format.
       def http_method_v1(args)
         url = Miradore.url[:v1] % args.merge(
           subdomain: @subdomain || args[:subdomain],
           auth: args.fetch(:auth, @auth),
           id: args.fetch(:id, nil),
-          item: self.class.to_s.split('::').last,
+          item: self.class.name&.demodulize,
           attribute: args.fetch(:attribute, Miradore.select_attributes),
           filter: args.fetch(:filter, nil),
           options: args.fetch(:options, nil)&.to_query&.sub('&', ',')
@@ -90,7 +118,7 @@ module Ruby
       end
 
       def transform(res, args = {})
-        return res if args.fetch(:skip_transform, false)
+        return res if args.fetch(:skip_transform, false) || res.is_a?(Net::HTTPClientError)
 
         args.merge!({ subdomain: args.fetch(:subdomain, @subdomain), auth: args.fetch(:auth, @auth) })
         if res.values.first.is_a?(Array)
@@ -100,21 +128,30 @@ module Ruby
         end
         self.class.new(args.merge(res.values.first&.transform_keys(&:downcase)))
       rescue StandardError
-        { error: "#{self.class.to_s.split('::').last}(s) not found", status: :not_found }
+        { error: "#{self.class.name&.demodulize}(s) not found", status: :not_found }
       end
 
     end
 
+    # Ruby::Miradore::Device class
+    # This class is used to perform actions on devices using the API v2 version.
+    # +Device+ class implements the following methods to perform actions on devices:
+    # * lock - Lock the device remotely
+    # * lostmode - Activates the lost mode actions on cellphone devices (Android, iOS, WindowsPhone) only.
+    # * reboot - Reboot the device remotely, this action depends on the device OS.
+    # * wipe - Wipe the device remotely, this action depends on the device OS.
+    # * location - Retrieve the device location remotely only on mobile devices.
+    #
+    # @example Usage example for Ruby::Miradore::Device actions
+    #  Miradore::Device.new(subdomain: 'subdomain', auth: 'api_token').lock(id: 1)
+    # @example Usage example for Ruby::Miradore::Device actions but getting the device first using Request class
+    #  Miradore::Request.new(subdomain: 'subdomain', auth: 'api_token').call(id: 1).lock
     class Device < Request
       include HTTParty
       format :json
       headers "Content-Type": 'application/json'
       headers "Accept": 'application/json'
 
-      def initialize(args = {})
-        super args
-      end
-
       def lock(args = {})
         http_method(args.merge(method: :post, id: id, action: __method__))
       end
@@ -177,6 +214,7 @@ module Ruby
 
       private
 
+      # Generates the URL and calls the HTTParty method based on the arguments passed and using the API v2 format.
       def http_method(args)
         self.class.headers 'X-API-Key' => @auth || args[:auth]
         url = Miradore.url[:v2] % {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-miradore
 version: !ruby/object:Gem::Version
-  version: 4.4.2
+  version: 4.4.4
 platform: ruby
 authors:
 - Eduard Garcia Castelló
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 2023-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -168,9 +168,6 @@ files:
 - fixtures/vcr_cassettes/user_alredy_exist_in_miradore.yml
 - lib/ruby/miradore.rb
 - lib/ruby/miradore/version.rb
-- ruby-miradore-2.0.1.gem
-- ruby-miradore-2.0.2.gem
-- ruby-miradore-2.1.2.gem
 - ruby-miradore.gemspec
 homepage: https://github.com/eddygarcas/ruby-miradore
 licenses: