ruby-jss 4.1.1 → 4.2.0

data/lib/jamf/api/classic/api_objects/package.rb

@@ -1,4 +1,4 @@
-# Copyright 2023 Pixar
+# Copyright 2025 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -31,11 +31,17 @@ module Jamf
   # Classes
   #####################################
 
+  # @deprecated Use {Jamf::JPackage} instead.
+  # This class will be removed in a future release.
+  #
   # A Package in the JSS
   #
   # Also the API provides no access to the package's
   # file list (index), so indexing must be done separately (usually via Casper Admin)
   #
+  # For accessing packages via the Jamf Pro API, see {Jamf::JPackage}
+  # which provides access to the other package-related attributes such as manifests and
+  # installer file uploads
   class Package < Jamf::APIObject
 
     # Mix-Ins
@@ -220,8 +226,9 @@ module Jamf
     #
     # @return [String] The checksum of the file
     #
-    def self.calculate_checksum(filepath, type = DEFAULT_CHECKSUM_HASH_TYPE )
+    def self.calculate_checksum(filepath, type = DEFAULT_CHECKSUM_HASH_TYPE)
       raise ArgumentError, 'Unknown checksum hash type' unless CHECKSUM_HASH_TYPES.key? type
+
       CHECKSUM_HASH_TYPES[type].file(filepath).hexdigest
     end
 
@@ -319,10 +326,9 @@ module Jamf
       @send_notification = @init_data[:send_notification]
       @switch_with_package = @init_data[:switch_with_package] || DO_NOT_INSTALL
 
-      @checksum = @init_data[:hash_value] #ill be nil if no checksum
+      @checksum = @init_data[:hash_value] # ill be nil if no checksum
       @checksum_type = @checksum ? @init_data[:hash_type] : DEFAULT_CHECKSUM_HASH_TYPE
 
-
       # the receipt is the filename with any .zip extension removed.
       @receipt = @filename ? (Jamf::Client::RECEIPTS_FOLDER + @filename.to_s.sub(/.zip$/, '')) : nil
     end # init
@@ -357,8 +363,10 @@ module Jamf
     #
     def boot_volume_required=(new_val)
       return nil if new_val == @boot_volume_required
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, 'install_if_reported_available must be boolean true or false' unless Jamf::TRUE_FALSE.include? new_val
+
       @boot_volume_required = new_val
       @need_to_update = true
     end
@@ -387,8 +395,10 @@ module Jamf
     #
     def fill_existing_users=(new_val)
       return nil if new_val == @fill_existing_users
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, "fill_existing_users must be boolean 'true' or 'false'" unless Jamf::TRUE_FALSE.include? new_val
+
       @fill_existing_users = new_val
       @need_to_update = true
     end
@@ -401,8 +411,10 @@ module Jamf
     #
     def fill_user_template=(new_val)
       return nil if new_val == @fill_user_template
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, "fill_user_template must be boolean 'true' or 'false'" unless Jamf::TRUE_FALSE.include? new_val
+
       @fill_user_template = new_val
       @need_to_update = true
     end
@@ -415,6 +427,7 @@ module Jamf
     #
     def info=(new_val)
       return nil if new_val == @info
+
       # line breaks should be \r
       new_val = new_val.to_s.tr("\n", "\r")
       @info = new_val
@@ -429,8 +442,10 @@ module Jamf
     #
     def install_if_reported_available=(new_val)
       return nil if new_val == @install_if_reported_available
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, 'install_if_reported_available must be boolean true or false' unless Jamf::TRUE_FALSE.include? new_val
+
       @install_if_reported_available = new_val
       @need_to_update = true
     end
@@ -531,8 +546,10 @@ module Jamf
     #
     def priority=(new_val)
       return nil if new_val == @priority
+
       new_val = DEFAULT_PRIORITY if new_val.to_s.empty?
       raise Jamf::InvalidDataError, ':priority must be an integer from 1-20' unless PRIORITIES.include? new_val
+
       @priority = new_val
       @need_to_update = true
     end
@@ -545,8 +562,10 @@ module Jamf
     #
     def reboot_required=(new_val)
       return nil if new_val == @reboot_required
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, "reboot must be boolean 'true' or 'false'" unless Jamf::TRUE_FALSE.include? new_val
+
       @reboot_required = new_val
       @need_to_update = true
     end
@@ -588,8 +607,10 @@ module Jamf
     #
     def send_notification=(new_val)
       return nil if new_val == @send_notification
+
       new_val = false if new_val.to_s.empty?
       raise Jamf::InvalidDataError, 'send_notification must be boolean true or false' unless Jamf::TRUE_FALSE.include? new_val
+
       @send_notification = new_val
       @need_to_update = true
     end
@@ -602,6 +623,7 @@ module Jamf
     #
     def switch_with_package=(new_val)
       return nil if new_val == @switch_with_package
+
       new_val = nil if new_val.to_s.empty?
 
       raise Jamf::NoSuchItemError, "No package named '#{new_val}' exists in the JSS" if new_val && (!self.class.all_names(cnx: @cnx).include? new_val)
@@ -712,7 +734,7 @@ module Jamf
     #
     # @return [void]
     #
-    def reset_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
+    def reset_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil)
       type ||= DEFAULT_CHECKSUM_HASH_TYPE
 
       new_checksum = calculate_checksum(
@@ -754,7 +776,7 @@ module Jamf
     #
     # @return [String] The calculated checksum
     #
-    def calculate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
+    def calculate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil)
       type ||= DEFAULT_CHECKSUM_HASH_TYPE
       dp = self.class.fetch_dist_point(dist_point, cnx: @cnx)
 
@@ -798,8 +820,9 @@ module Jamf
     # @return [Boolean] false if there is no checksum for this pkg, otherwise,
     #   does the calculated checksum match the one stored for the pkg?
     #
-    def checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
+    def checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil)
       return false unless @checksum
+
       new_checksum = calculate_checksum(
         type: @checksum_type,
         local_file: local_file,
@@ -829,6 +852,7 @@ module Jamf
     #
     def update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true, dist_point: nil)
       raise Jamf::NoSuchItemError, "#{old_file_name} does not exist in the jss." unless @in_jss
+
       dp = self.class.fetch_dist_point(dist_point, cnx: @cnx)
 
       pkgs_dir = dp.mount(rw_pw, :rw) + DIST_POINT_PKGS_FOLDER.to_s
@@ -845,8 +869,6 @@ module Jamf
       nil
     end # update_master_filename
 
-
-
     # Delete the filename from the master distribution point, if it exists.
     #
     # If you'll be uploading several files you can specify unmount as false, and do it manually when all
@@ -970,9 +992,11 @@ module Jamf
           if mdp.username_password_required
             raise Jamf::MissingDataError, 'No password provided for http download' unless ro_pw
             raise Jamf::InvaldDatatError, 'Incorrect password for http access to distribution point.' unless mdp.check_pw(:http, ro_pw)
+
             # insert the name and pw into the uri
             # reserved_chars = Regexp.new("[^#{URI::REGEXP::PATTERN::UNRESERVED}]") # we'll escape all the chars that aren't unreserved
-            src_path = src_path.sub(%r{(https?://)(\S)}, "#{Regexp.last_match(1)}#{CGI.escape mdp.http_username.to_s}:#{CGI.escape ro_pw.to_s}@#{Regexp.last_match(2)}")
+            src_path = src_path.sub(%r{(https?://)(\S)},
+                                    "#{Regexp.last_match(1)}#{CGI.escape mdp.http_username.to_s}:#{CGI.escape ro_pw.to_s}@#{Regexp.last_match(2)}")
           end
 
         # or with filesharing?
@@ -985,9 +1009,7 @@ module Jamf
         src_path += "#{DIST_POINT_PKGS_FOLDER}/"
       end # if args[:alt_download_url]
 
-      if using_http
-        src_path += @filename.to_s unless no_filename_in_url
-      end
+      src_path += @filename.to_s if using_http && !no_filename_in_url
 
       # are we doing "fill existing users" or "fill user template"?
       do_feu = args[:feu] ? '-feu' : ''
@@ -1003,9 +1025,7 @@ module Jamf
       install_exit = Regexp.last_match(1) ? Regexp.last_match(1).to_i : nil
       install_exit ||= $CHILD_STATUS.exitstatus
 
-      if args.include? :unmount
-        mdp.unmount unless using_http
-      end
+      mdp.unmount if args.include?(:unmount) && !using_http
 
       install_exit.zero? ? true : false
     end
@@ -1032,6 +1052,7 @@ module Jamf
               'This package cannot be uninstalled. Please use CasperAdmin to index it and allow uninstalls'
       end
       raise Jamf::UnsupportedError, 'You must have root privileges to uninstall packages' unless JSS.superuser?
+
       args[:target] ||= '/'
 
       # are we doing "fill existing users" or "fill user template"?
@@ -1094,7 +1115,6 @@ module Jamf
 
     private
 
-
     # Return the REST XML for this pkg, with the current values,
     # for saving or updating
     #

data/lib/jamf/api/classic/api_objects/patch_external_source.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -48,7 +48,6 @@ module Jamf
     # It's also used in various error messages
     RSRC_OBJECT_KEY = :patch_external_source
 
-
     # Instance Methods
     #####################################
 
@@ -58,6 +57,7 @@ module Jamf
     #
     def enable
       return if enabled?
+
       validate_host_port('enable a patch source')
       @enabled = true
       @need_to_update = true
@@ -69,6 +69,7 @@ module Jamf
     #
     def disable
       return unless enabled?
+
       @enabled = false
       @need_to_update = true
     end
@@ -78,6 +79,7 @@ module Jamf
     def host_name=(newname)
       return if newname == host_name
       raise Jamf::InvalidDataError, 'names must be String' unless name.is_a? String
+
       @host_name = name
       @need_to_update = true
     end
@@ -89,6 +91,7 @@ module Jamf
     def port=(new_port)
       return if new_port == port
       raise Jamf::InvalidDataError, 'ports must be Integers' unless port.is_a? Integer
+
       @port = new_port
       @need_to_update = true
     end
@@ -99,6 +102,7 @@ module Jamf
     #
     def use_ssl
       return if ssl_enabled?
+
       @ssl_enabled = true
       @need_to_update = true
     end
@@ -110,6 +114,7 @@ module Jamf
     #
     def no_ssl
       return unless ssl_enabled?
+
       @ssl_enabled = false
       @need_to_update = true
     end

data/lib/jamf/api/classic/api_objects/patch_internal_source.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/patch_policy.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/patch_title/version.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/classic/api_objects/patch_title.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -58,7 +58,6 @@ module Jamf
   #
   class PatchTitle < Jamf::APIObject
 
-    include Jamf::Sitable
     include Jamf::Categorizable
     include Jamf::Creatable
     include Jamf::Updatable
@@ -437,7 +436,10 @@ module Jamf
       return @versions unless @versions.empty?
 
       # if we are in jss, and versions is empty, re-fetch them
-      @versions = self.class.fetch(id: id).versions
+      # this SHOULDN't cause a loop, and shouldn't even ever happen
+      # because for the title to be active and fetchable, there must be
+      # at least one version.
+      @versions = self.class.fetch(id: id, cnx: cnx).versions
     end
 
     # @return [Hash] Subset of @versions, containing those which have packages
@@ -536,7 +538,6 @@ module Jamf
       add_changed_pkg_xml obj unless @changed_pkgs.empty?
 
       add_category_to_xml doc
-      add_site_to_xml doc
 
       doc.to_s
     end # rest_xml

data/lib/jamf/api/classic/api_objects/peripheral.rb

@@ -1,4 +1,4 @@
-### Copyright 2023 Pixar
+### Copyright 2025 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -43,7 +43,7 @@ module Jamf
   ###
   ### @see Jamf::APIObject
   ###
-  class Peripheral  < Jamf::APIObject
+  class Peripheral < Jamf::APIObject
 
     #####################################
     ### MixIns
@@ -65,7 +65,7 @@ module Jamf
     #####################################
 
     ### The base for REST resources of this class
-    RSRC_BASE = "peripherals"
+    RSRC_BASE = 'peripherals'
 
     ### the hash key used for the JSON list output of all objects in the JSS
     RSRC_LIST_KEY = :peripherals
@@ -100,11 +100,9 @@ module Jamf
     ### @return [String] the "bar code 1" value
     attr_reader :bar_code_1
 
-
     ### @return [String] the "bar code 2" value
     attr_reader :bar_code_2
 
-
     ### @return [Integer] the id number of the computer to which  this periph is connected
     attr_reader :computer_id
 
@@ -116,25 +114,26 @@ module Jamf
     ### @see APIObject
     ###
     def initialize(**args)
-
       ### periphs don't really have names, and the JSS module list method for
       ### periphs gives the computer_id as the name, so give it a temp
       ### name of "-1", which shouldn't ever exist in the JSS
-      args[:name] ||= "-1"
+      args[:name] ||= '-1'
 
       super
 
       if args[:id] == :new
-        raise Jamf::InvalidDataError, "New Peripherals must have a :type, which must be one of those defined in the JSS." unless args[:type]
+        raise Jamf::InvalidDataError, 'New Peripherals must have a :type, which must be one of those defined in the JSS.' unless args[:type]
+
         @type = args[:type]
         raise Jamf::InvalidDataError, "No peripheral type '#{@type}' in the JSS" unless Jamf::PeripheralType.all_names(:refresh, cnx: @cnx).include? @type
+
         @fields = {}
         @rest_rsrc = 'peripherals/id/-1'
-        @site = "None"
+        @site = 'None'
         return
       end
 
-      @type =  @init_data[:general][:type]
+      @type = @init_data[:general][:type]
       @site = Jamf::APIObject.get_name(@init_data[:general][:site])
       @bar_code_1 = @init_data[:general][:bar_code_1]
       @bar_code_2 = @init_data[:general][:bar_code_2]
@@ -142,15 +141,12 @@ module Jamf
 
       ### fill in the fields
       @fields = {}
-      @init_data[:general][:fields].each{|f| @fields[f[:name]] = f[:value] }
+      @init_data[:general][:fields].each { |f| @fields[f[:name]] = f[:value] }
 
       ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= Jamf::PeripheralType.fetch(:name => @type).fields.compact
-
-
+      @field_defs ||= Jamf::PeripheralType.fetch(name: @type).fields.compact
     end # initialize
 
-
     ###
     ### reset the restrsrc after creation
     ###
@@ -165,7 +161,7 @@ module Jamf
     ###
     ### periphs don't have names
     ###
-    def name= (newname)
+    def name=(_newname)
       raise Jamf::UnsupportedError, "Peripherals don't have names."
     end
 
@@ -175,9 +171,7 @@ module Jamf
     ###   Each key is the fields name, as a String
     ###   and the value is the fields value, also as a String
     ###
-    def fields
-      @fields
-    end
+    attr_reader :fields
 
     ###
     ### Set the value of a field. It will be checked to ensure validity.
@@ -201,12 +195,11 @@ module Jamf
     ###
     ### @return [void]
     ###
-    def bar_code_1= (new_value)
-        @bar_code_1 = new_value
-        @need_to_update = true
+    def bar_code_1=(new_value)
+      @bar_code_1 = new_value
+      @need_to_update = true
     end
 
-
     ###
     ### Set the value of barcode 2
     ###
@@ -214,12 +207,11 @@ module Jamf
     ###
     ### @return [void]
     ###
-    def bar_code_2= (new_value)
-        @bar_code_2 = new_value
-        @need_to_update = true
+    def bar_code_2=(new_value)
+      @bar_code_2 = new_value
+      @need_to_update = true
     end
 
-
     ###
     ### Associate this peripheral with a computer.
     ###
@@ -230,15 +222,16 @@ module Jamf
     def associate(computer)
       if computer =~ /^d+$/
         raise Jamf::NoSuchItemError, "No computer in the JSS with id #{computer}" unless Jamf::Computer.all_ids(cnx: @cnx).include? computer
+
         @computer_id = computer
       else
         raise Jamf::NoSuchItemError, "No computer in the JSS with name #{computer}" unless Jamf::Computer.all_names(cnx: @cnx).include? computer
+
         @computer_id = Jamf::Computer.map_all_ids_to(:name, cnx: @cnx).invert[computer]
       end
       @need_to_update = true
     end
 
-
     ###
     ### Disassociate this peripheral from any computer.
     ###
@@ -252,7 +245,6 @@ module Jamf
       @need_to_update = true
     end
 
-
     #################################
     ### Private Methods below here
     private
@@ -266,20 +258,22 @@ module Jamf
     ###
     def check_field(field, value)
       ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= Jamf::PeripheralType.fetch(:name => @type, cnx: @cnx).fields.compact
+      @field_defs ||= Jamf::PeripheralType.fetch(name: @type, cnx: @cnx).fields.compact
 
       ### we must have the right number of fields, and they must have the same names
       ### as the definition
-      required_fields = @field_defs.map{|f| f[:name]}
-      raise Jamf::InvalidDataError, "Peripherals of type '#{@type}' doesn't have a field '#{field}', they only have: #{required_fields.join(', ')}" unless required_fields.include? field
+      required_fields = @field_defs.map { |f| f[:name] }
+      unless required_fields.include? field
+        raise Jamf::InvalidDataError, 
+              "Peripherals of type '#{@type}' doesn't have a field '#{field}', they only have: #{required_fields.join(', ')}"
+      end
 
       ### any menu fields can only have values as defined by the type.
-      menu_flds = @field_defs.select{|f| f[:type] == "menu" }
+      menu_flds = @field_defs.select { |f| f[:type] == 'menu' }
       menu_flds.each do |mf|
         next unless mf[:name] == field
         raise Jamf::InvalidDataError, "The value for field '#{field}' must be one of: #{mf[:choices].join(', ')}" unless mf[:choices].include? value
-      end #if menu_flds.include? field
-
+      end # if menu_flds.include? field
     end # check fields
 
     ###
@@ -298,21 +292,17 @@ module Jamf
       general.add_element('computer_id').text = @computer_id
 
       fields = general.add_element('fields')
-      @fields.each do |n,v|
-        fld =  fields.add_element('field')
+      @fields.each do |n, v|
+        fld = fields.add_element('field')
         fld.add_element('name').text = n
         fld.add_element('value').text = v
       end
 
-      if has_location?
-        periph << location_xml
-      end
-      if has_purchasing?
-        periph << purchasing_xml
-      end
+      periph << location_xml if has_location?
+      periph << purchasing_xml if has_purchasing?
       add_site_to_xml doc
 
-      return doc.to_s
+      doc.to_s
     end # rest xml
 
     ### Aliases
@@ -330,4 +320,5 @@ module Jamf
     alias unassign disassociate
 
   end # class Peripheral
+
 end # module