ruby-jss 1.4.1 → 1.5.1

data/lib/jamf/api/resources/singleton_resources/locales.rb

@@ -0,0 +1,155 @@
+# Copyright 2020 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # A list of known timezones
+  class Locales < Jamf::SingletonResource
+
+    # Mix-Ins
+    #####################################
+
+    extend Jamf::Immutable
+
+    # Constants
+    #####################################
+
+    RSRC_VERSION = 'v1'.freeze
+
+    RSRC_PATH = 'locales'.freeze
+
+    OBJECT_MODEL = {
+
+      # @!attribute checkInFrequency
+      #   @return [integer]
+      locales: {
+        class: Jamf::Locale,
+        multi: true,
+        read_only: true,
+        aliases: [:list]
+      }
+
+    }.freeze # end OBJECT_MODEL
+
+    parse_object_model
+
+    # TEMP? until this endpoint is brought up to standards
+    # the data from the API is a raw Array, but it should be a
+    # Hash containing an array.
+    def initialize(data, cnx: Jamf.cnx)
+      data = { locales: data }
+      super data, cnx: cnx
+    end
+
+    # Class Methods
+    #####################################
+
+    # @return [Array<Jamf::Locale>] all the locales available
+    #
+    def self.list(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).locales
+    end
+
+    # Class level wrapper for #descriptions
+    def self.descriptions(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).descriptions
+    end
+    # how to alias a class method
+    singleton_class.send(:alias_method, :names, :descriptions)
+
+    # Class level wrapper for #identifiers
+    def self.identifiers(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).identifiers
+    end
+    singleton_class.send(:alias_method, :ids, :identifiers)
+
+    # Class level wrapper for #ids_by_desc
+    def self.ids_by_desc(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).ids_by_desc
+    end
+
+    # Class level wrapper for #descs_by_id
+    def self.descs_by_id(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).descs_by_id
+    end
+
+    # Class level wrapper for #id_for_desc
+    def self.id_for_desc(desc, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).id_for_desc desc
+    end
+
+    # Class level wrapper for #desc_for_id
+    def self.desc_for_id(id, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).desc_for_id id
+    end
+
+    # Instance Methods
+    #####################################
+
+    # @return [Array<String>] the available descriptions
+    def descriptions
+      @descriptions ||= locales.map(&:description)
+    end
+    alias names descriptions
+
+    # @return [Array<String>] the available identifiers
+    def identifiers
+      @identifiers ||= locales.map(&:identifier)
+    end
+    alias ids identifiers
+
+    # @return [Hash] name => code
+    def ids_by_desc
+      @ids_by_desc ||= locales.map { |l| [l.description, l.identifier] }.to_h
+    end
+
+    # @return [Hash] code => name
+    def descs_by_id
+      @descs_by_id ||= locales.map { |l| [l.identifier, l.description] }.to_h
+    end
+
+    # return an identifier from its description, case-insensitive
+    # @param desc[String] the description of a locale
+    # @return [String]
+    def id_for_desc(desc)
+      desc = descriptions.select { |n| n.casecmp? desc }.first
+      ids_by_desc[desc]
+    end
+
+    # return a description from its identifier, case-insensitive
+    # @param name[String] the identifier of a local
+    # @return [String]
+    def desc_for_id(id)
+      id = identifiers.select { |n| n.casecmp? id }.first
+      descs_by_id[id]
+    end
+
+  end # class
+
+end # module

data/lib/jamf/api/resources/singleton_resources/time_zones.rb

@@ -0,0 +1,213 @@
+# Copyright 2020 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # A list of known timezones
+  class TimeZones < Jamf::SingletonResource
+
+    # Mix-Ins
+    #####################################
+
+    extend Jamf::Immutable
+
+    # Constants
+    #####################################
+
+    RSRC_VERSION = 'v1'.freeze
+
+    RSRC_PATH = 'time-zones'.freeze
+
+    OBJECT_MODEL = {
+
+      # @!attribute checkInFrequency
+      #   @return [integer]
+      timeZones: {
+        class: Jamf::TimeZone,
+        multi: true,
+        read_only: true,
+        aliases: [:list]
+      }
+
+    }.freeze # end OBJECT_MODEL
+
+    parse_object_model
+
+    # TEMP? until this endpoint is brought up to standards
+    # the data from the API is a raw Array, but it should be a
+    # Hash containing an array.
+    def initialize(data, cnx: Jamf.cnx)
+      data = { timeZones: data }
+      super data, cnx: cnx
+    end
+
+
+
+    # Class Methods
+    #####################################
+
+    # @return [Array<Jamf::TimeZone>] all the zomes available
+    #
+    def self.list(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).timeZones
+    end
+
+    # Class level wrapper for #displayNames
+    def self.displayNames(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).displayNames
+    end
+    singleton_class.send(:alias_method, :names, :displayNames)
+
+    # Class level wrapper for #zoneIds
+    def self.zoneIds(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).zoneIds
+    end
+    singleton_class.send(:alias_method, :ids, :zoneIds)
+
+    # Class level wrapper for #regions
+    def self.regions(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).regions
+    end
+
+    # Class level wrapper for #ids_by_name
+    def self.ids_by_name(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).ids_by_name
+    end
+
+    # Class level wrapper for #names_by_id
+    def self.names_by_id(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).names_by_id
+    end
+
+    # Class level wrapper for #regions_by_id
+    def self.regions_by_id(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).regions_by_id
+    end
+
+    # Class level wrapper for #regions_by_name
+    def self.regions_by_name(refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).regions_by_name
+    end
+
+    # Class level wrapper for #id_for_name
+    def self.id_for_name(name, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).id_for_name name
+    end
+
+    # Class level wrapper for #name_for_id
+    def self.name_for_id(id, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).name_for_id id
+    end
+
+    # Class level wrapper for #region_for_name
+    def self.region_for_name(name, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).region_for_name name
+    end
+
+    # Class level wrapper for #name_for_id
+    def self.region_for_id(id, refresh = false, cnx: Jamf.cnx)
+      fetch(refresh, cnx: cnx).region_for_id id
+    end
+
+
+    # Instance Methods
+    #####################################
+
+    # @return [Array<String>] the available zone names
+    def displayNames
+      @names ||= timeZones.map(&:displayName)
+    end
+    alias names displayNames
+
+    # @return [Array<String>] the available zone ids
+    def zoneIds
+      @ids ||= timeZones.map(&:zoneId)
+    end
+    alias ids zoneIds
+
+    # @return [Array<String>] the available zone regions
+    def regions
+      @regions ||= timeZones.map(&:region).uniq
+    end
+
+    # @return [Hash] name => id
+    def ids_by_name
+      @ids_by_name ||= timeZones.map { |tz| [tz.displayName, tz.zoneId] }.to_h
+    end
+
+    # @return [Hash] id => name
+    def names_by_id
+      @names_by_id ||= timeZones.map { |tz| [tz.zoneId, tz.displayName] }.to_h
+    end
+
+    # @return [Hash] id => region
+    def regions_by_id
+      @regions_by_id ||= timeZones.map { |tz| [tz.zoneId, tz.region] }.to_h
+    end
+
+    # @return [Hash] name => region
+    def regions_by_name
+      @regions_by_name ||= timeZones.map { |tz| [tz.displayName, tz.region] }.to_h
+    end
+
+    # return a zone id from its name, case-insensitive
+    # @param name[String] the name of a zone
+    # @return [String]
+    def id_for_name(name)
+      name = names.select { |n| n.casecmp? name }.first
+      ids_by_name[name]
+    end
+
+    # return a zone name from its id, case-insensitive
+    # @param name[String] the name of a zone
+    # @return [String]
+    def name_for_id(id)
+      id = ids.select { |n| n.casecmp? id }.first
+      names_by_id[id]
+    end
+
+    # return a zone name from its id, case-insensitive
+    # @param name[String] the name of a zone
+    # @return [String]
+    def region_for_name(name)
+      name = names.select { |n| n.casecmp? name }.first
+      regions_by_name[name]
+    end
+
+    # return a zones from its id, case-insensitive
+    # @param name[String] the name of a zone
+    # @return [String]
+    def region_for_id(id)
+      id = ids.select { |n| n.casecmp? id }.first
+      regions_by_id[id]
+    end
+
+  end # class
+
+end # module

data/lib/jamf/validate.rb

@@ -37,7 +37,7 @@ module Jamf
   module Validate
 
     # The regular expression that matches a valid MAC address.
-    MAC_ADDR_RE = /^[a-f0-9]{2}(:[a-f0-9]{2}){5}$/i
+    MAC_ADDR_RE = /^[a-f0-9]{2}(:[a-f0-9]{2}){5}$/i.freeze
 
     # Validate the format and content of a MAC address
     #
@@ -50,6 +50,7 @@ module Jamf
     def self.mac_address(val, msg = nil)
       msg ||= "Not a valid MAC address: '#{val}'"
       raise Jamf::InvalidDataError, msg unless val =~ MAC_ADDR_RE
+
       val
     end
 
@@ -68,10 +69,11 @@ module Jamf
       ok = false unless parts.size == 4
       parts.each { |p| ok = false unless p.j_integer? && p.to_i < 256 && p.to_i >= 0 }
       raise Jamf::InvalidDataError, msg unless ok
+
       val
     end
 
-    # Does a give JSONObject class have a given JSON attribute?
+    # Does a given JSONObject class have a given JSON attribute?
     #
     # @param klass [<JSONObject] A class descended from JSONObject
     #
@@ -83,9 +85,24 @@ module Jamf
       raise "#{klass} is not a descendent of JSONObject" unless klass < Jamf::JSONObject
 
       raise Jamf::NoSuchItemError, "No attribute #{attr_name} for class #{klass}" unless klass::OBJECT_MODEL.key? attrib
+
       attr_name
     end
 
+    # Does a value exist in a given enum array?
+    #
+    # @param klass [<JSONObject] A class descended from JSONObject
+    #
+    # @param attr_name [Symbol] The attribute to validate
+    #
+    # @return [Symbol] The valid attribute
+    #
+    def self.in_enum(val, enum)
+      raise Jamf::InvalidDataError, "Value must be one of: #{enum.join ', '}" unless enum.include? val
+
+      val
+    end
+
     # Validate that a value doesn't already exist for a given identifier of
     # a given CollectionResource class
     #
@@ -116,14 +133,12 @@ module Jamf
       raise Jamf::AlreadyExistsError, msg
     end
 
+    TRUE_FALSE = [true, false].freeze
+
     # Confirm that the given value is a boolean value, accepting
-    # Strings and Symbols,  returning real booleans as needed
-    #
-    # Accepted True values: true, 'true', :true, 'yes', :yes
-    #
-    # Accepted False values: false, 'false', :false, 'no', :no
-    #
-    # all Strings and Symbols are case insensitive
+    # strings and symbols and returning real booleans as needed
+    # Accepts: true, false, 'true', 'false', 'yes', 'no', 't','f', 'y', or 'n'
+    # as strings or symbols, case insensitive
     #
     # @param val [Boolean,String,Symbol] The value to validate
     #
@@ -131,14 +146,36 @@ module Jamf
     #
     # @return [Boolean] the valid boolean
     #
-    def self.boolean(val, msg = nil)
-      msg ||= 'Value must be boolean true or false'
-      return true if val.to_s =~ /^(true|yes)$/i
-      return false if val.to_s =~ /^(false|no)$/i
+    def self.boolean(val, msg = 'Value must be true or false, or equivalent string or symbol')
+      return val if TRUE_FALSE.include? val
+      return true if val.to_s =~ /^(t(rue)?|y(es)?)$/i
+      return false if val.to_s =~ /^(f(alse)?|no?)$/i
 
       raise Jamf::InvalidDataError, msg
     end
 
+    # Confirm that a value provided is an integer or a string version
+    # of an integer, and return the string version
+    #
+    # The JPAPI specs say that all IDs are integers in strings
+    # tho, the endpoints are still implementing that in different versions.
+    #
+    # @param val[Object] the value to validate
+    #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @return [String] the valid integer-in-a-string
+    #
+    def self.j_id(val, msg = 'Value must be an Integer or an Integer in a String, e.g. "42"')
+      case val
+      when Integer
+        return val.to_s
+      when String
+        return val if val.j_integer?
+      end
+      raise Jamf::InvalidDataError, msg
+    end
+
     # Confirm that a value is an Integer or a String representation of an
     # Integer. Return the integer, or raise an error
     #
@@ -148,10 +185,10 @@ module Jamf
     #
     # @return [Integer] the valid integer
     #
-    def self.integer(val, msg = nil)
-      msg ||= 'Value must be an Integer'
+    def self.integer(val, msg = 'Value must be an Integer')
       val = val.to_i if val.is_a?(String) && val.j_integer?
       raise Jamf::InvalidDataError, msg unless val.is_a? Integer
+
       val
     end
 
@@ -164,10 +201,10 @@ module Jamf
     #
     # @return [Float] the valid float
     #
-    def self.float(val, msg = nil)
-      msg ||= 'Value must be a Floating Point number'
+    def self.float(val, msg = 'Value must be a Floating Point number')
       val = val.to_f if val.is_a?(String) && val.j_float?
-      raise Jamf::InvalidDataError, msg unless val.is_a? Flot
+      raise Jamf::InvalidDataError, msg unless val.is_a? Float
+
       val
     end
 
@@ -180,11 +217,12 @@ module Jamf
     #
     # @return [String] the valid String
     #
-    def self.string(val, msg = nil)
-      msg ||= 'Value must be a String'
+    def self.string(val, msg = 'Value must be a String')
       return Jamf::BLANK if val.nil?
+
       val = val.to_s if val.is_a? Symbol
       raise Jamf::InvalidDataError, msg unless val.is_a? String
+
       val
     end
 
@@ -197,10 +235,10 @@ module Jamf
     #
     # @return [String] the valid non-empty string
     #
-    def self.non_empty_string(val, msg = nil)
-      msg ||= 'value must be a non-empty String'
+    def self.non_empty_string(val, msg = 'value must be a non-empty String')
       val = val.to_s if val.is_a? Symbol
       raise Jamf::InvalidDataError, msg unless val.is_a?(String) && !val.empty?
+
       val
     end
 
@@ -214,11 +252,12 @@ module Jamf
     #
     # @return [String] the validated string
     #
-    def self.script_contents(val, msg = nil)
-      msg ||= "value must be a String starting with '#!'"
+    def self.script_contents(val, msg = "value must be a String starting with '#!'")
       raise Jamf::InvalidDataError, msg unless val.is_a?(String) && val.start_with?(SCRIPT_SHEBANG)
+
       val
     end
+
   end # module validate
 
 end # module JSS