ruby-jss 4.2.0b2 → 4.2.0

data/lib/jamf/api/jamf_pro/oapi_schemas/prestage_purchasing_information_v2.rb

@@ -0,0 +1,174 @@
+# Copyright 2025 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.
+#
+
+
+module Jamf
+
+  # This module is the namespace for all objects defined
+  # in the OAPI JSON schema under the components => schemas key
+  #
+  module OAPISchemas
+
+
+    # OAPI Object Model and Enums for: PrestagePurchasingInformationV2
+    #
+    #
+    #
+    # This class was automatically generated from the api/schema
+    # URL path on a Jamf Pro server version 11.6.1-t1718634702
+    #
+    # This class may be used directly, e.g instances of other classes may
+    # use instances of this class as one of their own properties/attributes.
+    #
+    # It may also be used as a superclass when implementing Jamf Pro API
+    # Resources in ruby-jss. The subclasses include appropriate mixins, and
+    # should expand on the basic functionality provided here.
+    #
+    #
+    # Container Objects:
+    # Other object models that use this model as the value in one
+    # of their attributes.
+    #  - Jamf::OAPISchemas::DeviceEnrollmentPrestageV2
+    #
+    # Sub Objects:
+    # Other object models used by this model's attributes.
+    #  
+    #
+    # Endpoints and Privileges:
+    # API endpoints and HTTP operations that use this object
+    # model, and the Jamf Pro privileges needed to access them.
+    #
+    #
+    #
+    class PrestagePurchasingInformationV2 < Jamf::OAPIObject
+
+      
+
+      OAPI_PROPERTIES = {
+
+        # @!attribute id
+        #   @return [String]
+        id: {
+          class: :j_id,
+          required: true,
+          identifier: :primary
+        },
+
+        # @!attribute leased
+        #   @return [Boolean]
+        leased: {
+          class: :boolean,
+          required: true
+        },
+
+        # @!attribute purchased
+        #   @return [Boolean]
+        purchased: {
+          class: :boolean,
+          required: true
+        },
+
+        # @!attribute appleCareId
+        #   @return [String]
+        appleCareId: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute poNumber
+        #   @return [String]
+        poNumber: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute vendor
+        #   @return [String]
+        vendor: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute purchasePrice
+        #   @return [String]
+        purchasePrice: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute lifeExpectancy
+        #   @return [Integer]
+        lifeExpectancy: {
+          class: :integer,
+          required: true
+        },
+
+        # @!attribute purchasingAccount
+        #   @return [String]
+        purchasingAccount: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute purchasingContact
+        #   @return [String]
+        purchasingContact: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute leaseDate
+        #   @return [String]
+        leaseDate: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute poDate
+        #   @return [String]
+        poDate: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute warrantyDate
+        #   @return [String]
+        warrantyDate: {
+          class: :string,
+          required: true
+        },
+
+        # @!attribute versionLock
+        #   @return [Integer]
+        versionLock: {
+          class: :integer,
+          required: true
+        }
+
+      } # end OAPI_PROPERTIES
+
+    end # class PrestagePurchasingInformationV2
+
+  end # module OAPISchemas
+
+end # module Jamf

data/lib/jamf/api/jamf_pro/oapi_schemas/prestage_scope_assignment_v2.rb

@@ -0,0 +1,94 @@
+# Copyright 2025 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.
+#
+
+
+module Jamf
+
+  # This module is the namespace for all objects defined
+  # in the OAPI JSON schema under the components => schemas key
+  #
+  module OAPISchemas
+
+
+    # OAPI Object Model and Enums for: PrestageScopeAssignmentV2
+    #
+    #
+    #
+    # This class was automatically generated from the api/schema
+    # URL path on a Jamf Pro server version 11.6.1-t1718634702
+    #
+    # This class may be used directly, e.g instances of other classes may
+    # use instances of this class as one of their own properties/attributes.
+    #
+    # It may also be used as a superclass when implementing Jamf Pro API
+    # Resources in ruby-jss. The subclasses include appropriate mixins, and
+    # should expand on the basic functionality provided here.
+    #
+    #
+    # Container Objects:
+    # Other object models that use this model as the value in one
+    # of their attributes.
+    #  - Jamf::OAPISchemas::PrestageScopeResponseV2
+    #
+    # Sub Objects:
+    # Other object models used by this model's attributes.
+    #  
+    #
+    # Endpoints and Privileges:
+    # API endpoints and HTTP operations that use this object
+    # model, and the Jamf Pro privileges needed to access them.
+    #
+    #
+    #
+    class PrestageScopeAssignmentV2 < Jamf::OAPIObject
+
+      
+
+      OAPI_PROPERTIES = {
+
+        # @!attribute serialNumber
+        #   @return [String]
+        serialNumber: {
+          class: :string
+        },
+
+        # @!attribute assignmentDate
+        #   @return [Jamf::Timestamp]
+        assignmentDate: {
+          class: Jamf::Timestamp,
+          format: 'date-time'
+        },
+
+        # @!attribute userAssigned
+        #   @return [String]
+        userAssigned: {
+          class: :string
+        }
+
+      } # end OAPI_PROPERTIES
+
+    end # class PrestageScopeAssignmentV2
+
+  end # module OAPISchemas
+
+end # module Jamf

data/lib/jamf/api/jamf_pro/oapi_schemas/v1_site.rb

@@ -0,0 +1,91 @@
+# Copyright 2025 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.
+#
+
+
+module Jamf
+
+  # This module is the namespace for all objects defined
+  # in the OAPI JSON schema under the components => schemas key
+  #
+  module OAPISchemas
+
+
+    # OAPI Object Model and Enums for: V1Site
+    #
+    #
+    #
+    # This class was automatically generated from the api/schema
+    # URL path on a Jamf Pro server version 11.6.1-t1718634702
+    #
+    # This class may be used directly, e.g instances of other classes may
+    # use instances of this class as one of their own properties/attributes.
+    #
+    # It may also be used as a superclass when implementing Jamf Pro API
+    # Resources in ruby-jss. The subclasses include appropriate mixins, and
+    # should expand on the basic functionality provided here.
+    #
+    #
+    # Container Objects:
+    # Other object models that use this model as the value in one
+    # of their attributes.
+    #  - Jamf::OAPISchemas::AuthorizationV1
+    #  - Jamf::OAPISchemas::ComputerGeneral
+    #  - Jamf::OAPISchemas::MobileDeviceDetailsV2
+    #
+    # Sub Objects:
+    # Other object models used by this model's attributes.
+    #  
+    #
+    # Endpoints and Privileges:
+    # API endpoints and HTTP operations that use this object
+    # model, and the Jamf Pro privileges needed to access them.
+    #  - '/v1/sites:GET' needs permissions:
+    #    - Read Sites
+    #
+    #
+    class V1Site < Jamf::OAPIObject
+
+      
+
+      OAPI_PROPERTIES = {
+
+        # @!attribute id
+        #   @return [String]
+        id: {
+          class: :j_id,
+          identifier: :primary
+        },
+
+        # @!attribute name
+        #   @return [String]
+        name: {
+          class: :string
+        }
+
+      } # end OAPI_PROPERTIES
+
+    end # class V1Site
+
+  end # module OAPISchemas
+
+end # module Jamf

data/lib/jamf/api/jamf_pro/oapi_schemas.rb

@@ -25,8 +25,31 @@
 # The module
 module Jamf
 
-  # This module is the namespace for all objects defined
+  # This module is the namespace for all JP API objects defined
   # in the OAPI JSON schema under the components => schemas key
+  #
+  # The classes in this module are the Ruby representations of the
+  # JSON schema objects (Hashes) in the Jamf Pro OAPI schema
+  #
+  # Each class is created from the JSON Object definition and other
+  # schema data, such as required attributes, the class or type of each
+  # attribute (which could be another OAPI object), and any enumurated
+  # values for attributes.
+  # The classes are all subclasses of Jamf::OAPIObject, which defines
+  # common methods for all OAPI objects, such as converting to and from
+  # JSON, and validating attribute values.
+  #
+  # These clases are used in various ways in ruby-jss:
+  # - As the value of an attribute in another OAPI object
+  # - As the parent class for a Jamf Pro API Resource class
+  # - As a representation of a JSON objects sent to or received from the API
+  #   (e.g. in a POST or PUT request)
+  #
+  # They are mostly generated automatically using the 'generate_object_models'
+  # executable in the 'bin' directory of ruby-jss. After generation the files needed
+  # are manually edited to add any needed functionality or clarifications of names
+  # etc, and then they are moved into the 'jamf/api/jamf_pro/oapi_schemas' directory.
+  #
   #####################################
   module OAPISchemas
 

data/lib/jamf/composer.rb

@@ -1,97 +1,104 @@
-### Copyright 2025 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.
-###
-###
-
-###
+# Copyright 2025 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.
+#
+#
+
 module Jamf
 
-  ###
-  ### This module provides two methods for building very simple Casper-happy .pkg and .dmg packages for deployment.
-  ###
-  ### Unlike Composer.app from JAMF, this module currently doesn't offer a way to do a before/after disk scan
-  ### and use the differences to build the root folder from which the package is built. Nor does the module support
-  ### editing the pre/post install scripts in .pkgs.
-  ###
-  ### The 'root folder', a folder representing the root filesystem of the target machine where the package will be installed,
-  ### must already exist and be fully populated and with correct permissions.
-  ###
+  # This module provides two methods for building very simple Casper-happy .pkg and .dmg
+  # packages for deployment.
+  #
+  # Unlike Composer.app from JAMF, this module currently doesn't offer a way to do a
+  # before/after disk scan
+  # and use the differences to build the root folder from which the package is built.
+  # Nor does the module support
+  # editing the pre/post install scripts in .pkgs.
+  #
+  # The 'root folder', a folder representing the root filesystem of the target machine
+  # where the package will be installed,
+  # must already exist and be fully populated and with correct permissions.
+  #
+  #
+  # TODO: Support building Distribution-style packages using the 'productbuild' tool,
+  # since they are needed for deploying packages via MDM - Component packages created
+  # by pkgbuild are not supported for MDM deployment.
+  #
   module Composer
 
     #####################################
-    ### Constants
+    # Constants
     #####################################
 
-    ### the apple pkgutil tool
+    # the apple pkgutil tool
     PKG_UTIL = Pathname.new '/usr/sbin/pkgutil'
 
-    ### The location of the cli tool for making .pkgs
+    # The location of the cli tool for making .pkgs
     PKGBUILD = Pathname.new '/usr/bin/pkgbuild'
 
-    ### the default bundle identifier prefix for pkgs
+    # the default bundle identifier prefix for pkgs
     PKG_BUNDLE_ID_PFX = 'ruby-jss-composer'.freeze
 
-    ### Apple's hdiutil for making dmgs
+    # Apple's hdiutil for making dmgs
     HDI_UTIL = '/usr/bin/hdiutil'.freeze
 
-    ### Where to save the output ?
+    # Where to save the output ?
     DEFAULT_OUT_DIR = Pathname.new '/Users/Shared'
 
-    ### Make a casper-happy .pkg out of a root folder, permissions are assumed to be correct.
-    ###
-    ### @param name[String] the name of the .pkg. The .pkg suffix will be added if not present
-    ###
-    ### @param version[String] the version of the .pkg, needed for building the .pkg
-    ###
-    ### @param root[String, Pathname] the path to the 'root folder' representing
-    ###   the root file system of the target install drive
-    ###
-    ### @param opts[Hash] the options for building the .pkg
-    ###
-    ### @options opts :pkg_id[String] the full package if for the new pkg.
-    ###   e.g. 'com.mycompany.myapp'
-    ###
-    ### @option opts :bundle_id_prefix[String] the pkg bundle identifier prefix.
-    ###   If no :pkg_id is provided, one is made using this prefix and
-    ###   the name provided. e.g. 'com.mycompany'
-    ###   Defaults to '{PKG_BUNDLE_ID_PFX}'. See 'man pkgbuild' for more info
-    ###
-    ### @option opts :out_dir[String,Pathname] he folder in which the .pkg will be
-    ###   created. Defaults to {DEFAULT_OUT_DIR}
-    ###
-    ### @option opts :preserve_ownership[Boolean] If true, the owner/group of the
-    ###   rootpath are preserved.
-    ###   Default is false: they become the pkgbuild/installer 'recommended'
-    ###   (root/wheel or root/admin)
-    ###
-    ### @option opts :signing_identity[String] the optional name of the signing identity (certificate) to
-    ###   use for signing the pkg. See `man pkgbuild` for details
-    ###
-    ### @option opts :signing_options[String] the optional string of options to pass to pkgbuild.
-    ###  See `man pkgbuild` for details
-    ###
-    ### @return [Pathname] the local path to the new .pkg
-    ###
+    # Make a casper-happy .pkg out of a root folder, permissions are assumed to be correct.
+    #
+    # @param name[String] the name of the .pkg. The .pkg suffix will be added if not present
+    #
+    # @param version[String] the version of the .pkg, needed for building the .pkg
+    #
+    # @param root[String, Pathname] the path to the 'root folder' representing
+    #   the root file system of the target install drive
+    #
+    # @param opts[Hash] the options for building the .pkg
+    #
+    # @options opts :pkg_id[String] the full package if for the new pkg.
+    #   e.g. 'com.mycompany.myapp'
+    #
+    # @option opts :bundle_id_prefix[String] the pkg bundle identifier prefix.
+    #   If no :pkg_id is provided, one is made using this prefix and
+    #   the name provided. e.g. 'com.mycompany'
+    #   Defaults to '{PKG_BUNDLE_ID_PFX}'. See 'man pkgbuild' for more info
+    #
+    # @option opts :out_dir[String,Pathname] he folder in which the .pkg will be
+    #   created. Defaults to {DEFAULT_OUT_DIR}
+    #
+    # @option opts :preserve_ownership[Boolean] If true, the owner/group of the
+    #   rootpath are preserved.
+    #   Default is false: they become the pkgbuild/installer 'recommended'
+    #   (root/wheel or root/admin)
+    #
+    # @option opts :signing_identity[String] the optional name of the signing identity (certificate) to
+    #   use for signing the pkg. See `man pkgbuild` for details
+    #
+    # @option opts :signing_options[String] the optional string of options to pass to pkgbuild.
+    #  See `man pkgbuild` for details
+    #
+    # @return [Pathname] the local path to the new .pkg
+    #
     def self.mk_pkg(name, version, root, **opts)
       raise NoSuchItemError, "Missing pkgbuild tool. Please make sure you're running 10.8 or later." unless PKGBUILD.executable?
 
@@ -111,28 +118,28 @@ module Jamf
         signing = ''
       end # if opts[:signing_identity]
 
-      ### first, run 'analyze' to get a 'component plist' in which we can change some settings
-      ### for any bundles in the root (bundles like .apps, frameworks, plugins, etc..)
-      ###
-      ### we edit the settings thus:
-      ### BundleOverwriteAction = upgrade, totally replace any version current on disk
-      ### BundleIsVersionChecked = false, allow us to install regardless of what version is currently installed
-      ### BundleIsRelocatable = false,  if there's a version of this in some other location, Do Not move this one there after installation
-      ### BundleHasStrictIdentifier = false, don't care if there's something at the install path with a different bundle id.
-      ###
-      ### In other words, just install the thing!
-      ### (see 'man pkgbuild' for more info)
-      ###
-      ###
+      # first, run 'analyze' to get a 'component plist' in which we can change some settings
+      # for any bundles in the root (bundles like .apps, frameworks, plugins, etc..)
+      #
+      # we edit the settings thus:
+      # BundleOverwriteAction = upgrade, totally replace any version current on disk
+      # BundleIsVersionChecked = false, allow us to install regardless of what version is currently installed
+      # BundleIsRelocatable = false,  if there's a version of this in some other location, Do Not move this one there after installation
+      # BundleHasStrictIdentifier = false, don't care if there's something at the install path with a different bundle id.
+      #
+      # In other words, just install the thing!
+      # (see 'man pkgbuild' for more info)
+      #
+      #
       comp_plist_out = Pathname.new "/tmp/#{PKG_BUNDLE_ID_PFX}-#{pkg_filename}.plist"
       system "#{PKGBUILD} --analyze --root '#{root}' '#{comp_plist_out}'"
       comp_plist = JSS.parse_plist comp_plist_out
 
-      ### if the plist is empty, there are no bundles in the pkg
+      # if the plist is empty, there are no bundles in the pkg
       if comp_plist[0].nil?
         comp_plist_arg = ''
       else
-        ### otherwise, edit the bundle dictionaries
+        # otherwise, edit the bundle dictionaries
         comp_plist.each do |bndl|
           bndl.delete 'ChildBundles' if bndl['ChildBundles']
           bndl['BundleOverwriteAction'] = 'upgrade'
@@ -140,12 +147,12 @@ module Jamf
           bndl['BundleIsRelocatable'] = false
           bndl['BundleHasStrictIdentifier'] = false
         end
-        ### write out the edits
+        # write out the edits
         comp_plist_out.open('w') { |f| f.write JSS.xml_plist_from(comp_plist) }
         comp_plist_arg = "--component-plist '#{comp_plist_out}'"
       end
 
-      ### now build the pkg
+      # now build the pkg
       begin
         it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}'"
 
@@ -157,18 +164,18 @@ module Jamf
       Pathname.new pkg_out
     end # mk_dot_pkg
 
-    ###
-    ### Make a casper-happy .dmg out of a root folder, permissions are assumed to be correct.
-    ###
-    ### @param name[String] The name of the .dmg, the suffix will be added if needed
-    ###
-    ### @param root[String, Pathname]  the path to the "root folder" representing the root file system of the target install drive
-    ###
-    ### @param out_dir[String, Pathname] the folder in which the .pkg will be created. Defaults to {DEFAULT_OUT_DIR}
-    ###
-    ### @return [Pathname] the local path to the new .dmg
-    ###
-    ###
+    #
+    # Make a casper-happy .dmg out of a root folder, permissions are assumed to be correct.
+    #
+    # @param name[String] The name of the .dmg, the suffix will be added if needed
+    #
+    # @param root[String, Pathname]  the path to the "root folder" representing the root file system of the target install drive
+    #
+    # @param out_dir[String, Pathname] the folder in which the .pkg will be created. Defaults to {DEFAULT_OUT_DIR}
+    #
+    # @return [Pathname] the local path to the new .dmg
+    #
+    #
     def self.mk_dmg(name, root, out_dir = DEFAULT_OUT_DIR)
       dmg_filename = "#{name}.dmg"
       dmg_vol = name
@@ -178,7 +185,7 @@ module Jamf
         dmg_out.rename mv_to
       end # if dmg out exist
 
-      ### TODO - this may need to be sudo'd to handle proper internal permissions.
+      # TODO: - this may need to be sudo'd to handle proper internal permissions.
       system "#{HDI_UTIL} create -volname '#{dmg_vol}' -scrub -srcfolder '#{root}' '#{dmg_out}'"
 
       raise 'There was an error building the .dmg' unless $?.exitstatus.zero?

data/lib/jamf/oapi_validate.rb

@@ -163,6 +163,7 @@ module Jamf
 
       # try to instantiate the class with the value. It should raise an error
       # if not good
+      # TODO: Does this method name need to be in Jamf::JPAPIResource::NEW_CALLERS
       klass.new val
     rescue => e
       raise_invalid_data_error(msg || "#{attr_name} value must be a #{klass}, or #{klass}.new must accept it as the only parameter, but #{klass}.new raised: #{e.class}: #{e}")