ruby-jss 3.2.1 → 4.0.0b1

data/lib/jamf/api/jamf_pro/api_objects/api_role.rb

@@ -0,0 +1,134 @@
+# Copyright 2023 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.
+#
+#
+
+# Manually require our OAPISchema....
+######################################
+# because this file defining Jamf::APIRole is at
+#      lib/jamf/api/jamf_pro/api_objects/api_role.rb
+# has the same filename as the file defining Jamf::OAPISchemas::ApiRole
+#      lib/jamf/api/jamf_pro/oapi_schemas/api_role.rb
+# telling zeitwerk to use the file 'api_role.rb' to load Jamf::APIRole
+# confuses it because it also finds the other one.
+#
+# So instead we'll tell it to ignore lib/jamf/api/jamf_pro/oapi_schemas/api_role.rb
+# and we'll load that manually here
+#
+require 'jamf/api/jamf_pro/oapi_schemas/api_role'
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # An API Role in the Jamf Pro API
+  #
+  # API Roles are predefined sets of privileges that can be assigned to API Clients, aka API Integrations.
+  #
+  class APIRole < Jamf::OAPISchemas::ApiRole
+
+    include Jamf::CollectionResource
+    extend Jamf::Filterable
+
+    ########### RELATED OAPI OBJECTS
+    # These objects should be OAPIObjects, NOT subclasses of them and
+    # not Collection or Singleton resources.
+    #
+    # TODO: See if these constants can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The OAPI object class we get back from a 'list' query to get the
+    # whole collection, or a subset of it. It contains a :results key
+    # which is an array of data for objects of the parent class.
+    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::ApiRoleResult
+
+    # The OAPI object class we send with a POST request to make a new member of
+    # the collection in Jamf. This is usually the same as the parent class.
+    POST_OBJECT = Jamf::OAPISchemas::ApiRoleRequest
+
+    # The OAPI object class we send with a PUT request to change an object in
+    # Jamf by specifying all its values. Most updates happen this way,
+    # and this is usually the same as the parent class
+    PUT_OBJECT = Jamf::OAPISchemas::ApiRoleRequest
+
+    # The OAPI object we send with a PATCH request to change an object in
+    # Jamf by replacing only some of its values. This is never the same as the
+    # parent class, and is usually used when many or most of the data about an
+    # object cannot be changed via the API.
+    # PATCH_OBJECT = Jamf::OAPISchemas::Building
+
+    ############# API PATHS
+
+    # The path for GETting the list of all objects in the collection, possibly
+    # filtered, sorted, and/or paged
+    # REQUIRED for all collection resources
+    #
+    # GET_PATH, POST_PATH, PUT_PATH, PATCH_PATH, and DELETE_PATH are automatically
+    # assumed from the LIST_PATH if they follow the standards:
+    # - GET_PATH = "#{LIST_PATH}/id"
+    #   - fetch an object from the collection
+    # - POST_PATH = LIST_PATH
+    #   - create a new object in the collection
+    # - PUT_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing all its values back.
+    #     Most objects use this or PATCH but not both
+    # - PATCH_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing some of its values back
+    #     Most objects use this or PUT but not both
+    # - DELETE_PATH = "#{LIST_PATH}/id"
+    #   - delete an object from the collection
+    #
+    # If those paths differ from the standards, the constants must be defined
+    # here
+    #
+    LIST_PATH = 'v1/api-roles'.freeze
+
+    # The path that returns a list of all available privs
+    AVAILABLE_PRIVS_PATH = 'v1/api-role-privileges'
+
+    # Identifiers not marked in the superclass's OAPI_PROPERTIES constant
+    # which usually only identifies ':id'
+    ALT_IDENTIFIERS = %i[displayName].freeze
+
+    # Must define this when extending Filterable
+    FILTER_KEYS = %i[
+      id displayName
+    ].freeze
+
+    # Class Methods
+    ###############################
+
+    # @return [Array<String>] All available privileges that can be granted via an API Role
+    #
+    def self.available_privs(cnx: Jamf.cnx)
+      cnx.jp_get(AVAILABLE_PRIVS_PATH)[:privileges]
+    end
+
+    # Instance Attributes and Methods
+    ###########################
+
+  end # class
+
+end # module

data/lib/jamf/api/jamf_pro/api_objects/computer_prestage.rb

@@ -1,5 +1,8 @@
 # Copyright 2023 Pixar
+#
+# frozen_string_literal: true
 
+#
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in
@@ -50,16 +53,16 @@ module Jamf
     # The OAPI object class we get back from a 'list' query to get the
     # whole collection, or a subset of it. It contains a :results key
     # which is an array of data for objects of the parent class.
-    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::ComputerPrestageSearchResultsV2
+    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::ComputerPrestageSearchResultsV3
 
     # The OAPI object class we send with a POST request to make a new member of
     # the collection in Jamf. This is usually the same as the parent class.
-    POST_OBJECT = Jamf::OAPISchemas::PostComputerPrestageV2
+    POST_OBJECT = Jamf::OAPISchemas::PostComputerPrestageV3
 
     # The OAPI object class we send with a PUT request to change an object in
     # Jamf by specifying all its values. Most updates happen this way,
     # and this is usually the same as the parent class
-    PUT_OBJECT = Jamf::OAPISchemas::PutComputerPrestageV2
+    PUT_OBJECT = Jamf::OAPISchemas::PutComputerPrestageV3
 
     ############# API PATHS
     # TODO: See if these paths can be auto-generated from the
@@ -70,10 +73,16 @@ module Jamf
     #
     # REQUIRED for all collection resources
     #
-    # GET_, PUT_, PATCH_, POST_, and DELETE_ paths don't need to be
+    # GET_, PUT_, PATCH_, POST_, and DELETE_ paths for instances don't need to be
     # defined if they are the same as LIST_PATH (followed by an id if needed)
     #
-    LIST_PATH = 'v2/computer-prestages'.freeze
+    # See the methods get_path, put_path, etc, in  Jamf::CollectionResource::ClassMethods
+    #
+    LIST_PATH = 'v3/computer-prestages'
+
+    # As of Jamf Pro 10.50, the scope-related endpoints for computer prestages
+    # are still in v2
+    SCOPE_PATH_PREFIX = 'v2/computer-prestages'
 
     # alt and non-unique idents are defined in the prestage module
 

data/lib/jamf/api/jamf_pro/api_objects/mobile_device_prestage.rb

@@ -75,11 +75,12 @@ module Jamf
     # GET_, PUT_, PATCH_, POST_, and DELETE_ paths don't need to be
     # defined if they are the same as LIST_PATH (followed by an id if needed)
     #
+    # See the methods get_path, put_path, etc, in  Jamf::CollectionResource::ClassMethods
+    #
     LIST_PATH = 'v2/mobile-device-prestages'.freeze
 
     # alt and non-unique idents are defined in the prestage module
 
-
     # TODO:  Implement the 'syncs' stuff
 
   end # class

data/lib/jamf/api/jamf_pro/mixins/collection_resource.rb

@@ -744,7 +744,7 @@ module Jamf
     # make sure that required values are not nil
     ############################################
     def validate_for_create
-      self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
+      self.class::POST_OBJECT::OAPI_PROPERTIES.each do |attr_name, attr_def|
         next unless attr_def[:required]
         next unless send(attr_name).nil?
 

data/lib/jamf/api/jamf_pro/mixins/prestage.rb

@@ -85,18 +85,19 @@ module Jamf
       end
 
       # Return all scoped serial numbers and the id of the prestage
-      # they are assigned to. Data is cached, use a truthy first param to refresh.
+      # they are assigned to.
       #
-      # @param refresh[Boolean] re-read the list from the API?
+      # @param refresh[Boolean] re-read the list from the API? DEPRECATED:
+      #   the data is always read from the API. If making many calls at once,
+      #   consider capturing serials_by_prestage_id in your own variable
       #
       # @param cnx[Jamf::Connection] the API connection to use
       #
       # @return [Hash {String => Integer}] The Serials and prestage IDs
       ######################
-      def serials_by_prestage_id(_refresh = nil, cnx: Jamf.cnx)
-        scope_path ||= "#{self::LIST_PATH}/#{SCOPE_PATH}"
+      def serials_by_prestage_id(refresh = false, cnx: Jamf.cnx) # rubocop:disable Lint/UnusedMethodArgument
         api_reponse = ALL_SCOPES_OBJECT.new cnx.jp_get(scope_path)
-        api_reponse.serialsByPrestageId.transform_keys!(&:to_s)
+        api_reponse.serialsByPrestageId.transform_keys(&:to_s)
       end
 
       # Get the assigned serialnumbers for a given prestage, without
@@ -105,15 +106,17 @@ module Jamf
       # @paream prestage_ident [Integer, String] the id or name of
       #   an existing prestage.
       #
-      # @param refresh[Boolean] re-read the list from the API?
+      # @param refresh[Boolean] re-read the list from the API? DEPRECATED:
+      #   the data is always read from the API. If making many calls at once,
+      #   consisider capturing serials_by_prestage_id in your own variable and using
+      #   it as this method does
       #
       # @param cnx[Jamf::Connection] the API connection to use
       #
       # @return [Array<String>] the SN's assigned to the prestage
       ######################
-      def serials_for_prestage(prestage_ident, _refresh = nil, cnx: Jamf.cnx)
+      def serials_for_prestage(prestage_ident, refresh = false, cnx: Jamf.cnx) # rubocop:disable Lint/UnusedMethodArgument
         id = valid_id prestage_ident, cnx: cnx
-
         raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id
 
         serials_by_prestage_id(cnx: cnx).select { |_sn, psid| id == psid }.keys
@@ -127,12 +130,12 @@ module Jamf
       # of your Device Enrollment instances, use Jamf::DeviceEnrollment.include?
       #
       # @param sn [String] the serial number to look for
-      #      #
+      #
       # @param cnx[Jamf::Connection] the API connection to use
       #
-      # @return [Integer, nil] The id of prestage to which the SN is assigned
+      # @return [String, nil] The id of prestage to which the SN is assigned
       #
-      def assigned_prestage_id(sn, _refresh = nil, cnx: Jamf.cnx)
+      def assigned_prestage_id(sn, cnx: Jamf.cnx)
         serials_by_prestage_id(cnx: cnx)[sn]
       end
 
@@ -150,8 +153,6 @@ module Jamf
       #
       # @param sn [String] the serial number to look for
       #
-      # @param refresh[Boolean] re-read the list from the API?
-      #
       # @param prestage [Integer, String] If provided, the id or name of
       #   an existing prestage in which to look for the sn. if omitted, all
       #   prestages are searched.
@@ -160,8 +161,9 @@ module Jamf
       #
       # @return [Boolean] Is the sn assigned, at all or to the given prestage?
       #
-      def assigned?(sn, prestage: nil, cnx: Jamf.cnx, refresh: nil)
+      def assigned?(sn, prestage: nil, cnx: Jamf.cnx)
         assigned_id = assigned_prestage_id(sn, cnx: cnx)
+
         # it isn't assigned at all
         return false unless assigned_id
 
@@ -175,47 +177,17 @@ module Jamf
         psid == assigned_id
       end
 
-      # We subtract the serials_by_prestage_id.keys from all known ADE SNs
-      # rather than just looking for Jamf::DeviceEnrollment.devices  with status
-      # REMOVED, because of the delay in updating the status for
-      # Jamf::DeviceEnrollment::Devices, which must come from apple.
-      #
-      # @return [Array<String>] The serial numbers of devices that are in ADE but
-      #    not assigned to any prestage
-      #
-      def unassigned_sns(cnx: Jamf.cnx)
-        type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
-        Jamf::DeviceEnrollment.device_sns(type: type, cnx: cnx) - serials_by_prestage_id(:refresh, cnx: cnx).keys
-      end
-
-      # @return [Array<String>] The serial numbers of known hardware not in ADE
-      #   at all
-      # TODO: move this to Jamf::DeviceEnrollment
-      # def sns_not_in_device_enrollment
-      #   # type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
-      #   nil # TODO: this, once MobileDevice  & Computer classes are implemented
-      # end
-
       # Assign one or more serialNumbers to a prestage
       # @return [Jamf::OAPISchemas::PrestageScopeResponseV2] the new scope for the prestage
       def assign(*sns_to_assign, to_prestage:, cnx: Jamf.cnx)
         prestage_id = valid_id to_prestage
         raise Jamf::NoSuchItemError, "No #{self} matching '#{to_prestage}'" unless prestage_id
 
-        # all sns_to_assign must be in ADE
-        not_in_dep = sns_to_assign - Jamf::DeviceEnrollment.device_sns
-        raise Jamf::UnsupportedError, "These SNs are not in any Device Enrollment instance: #{not_in_dep.join ', '}" unless not_in_dep.empty?
-
-        # all sns_to_assign must currently be unassigned.
-        already_assigned = sns_to_assign - unassigned_sns
-        raise Jamf::UnsupportedError, "These SNs are already assigned to a prestage: #{already_assigned.join ', '}" unless already_assigned.empty?
-
         # upcase all sns
         sns_to_assign.map!(&:to_s)
         sns_to_assign.map!(&:upcase)
 
-        # get the prestage name
-        prestage_name = map_all(:id, to: :displayName)[prestage_id]
+        # get the current scope of the prestage
         spath = scope_path(prestage_id)
         scope = INSTANCE_SCOPE_OBJECT.new cnx.get(spath)
 
@@ -224,7 +196,7 @@ module Jamf
         new_scope_sns += sns_to_assign
         new_scope_sns.uniq!
 
-        update_scope(prestage_name, spath, new_scope_sns, scope.versionLock, cnx)
+        update_scope(spath, new_scope_sns, scope.versionLock, cnx)
       end # self.assign
 
       # Unassign one or more serialNumber from a prestage
@@ -237,28 +209,29 @@ module Jamf
         sns_to_unassign.map!(&:to_s)
         sns_to_unassign.map!(&:upcase)
 
-        # get the prestage name
-        prestage_name = map_all(:id, to: :displayName)[prestage_id]
+        # get the current scope of the prestage
         spath = scope_path(prestage_id)
         scope = INSTANCE_SCOPE_OBJECT.new cnx.get(spath)
 
         new_scope_sns = scope.assignments.map(&:serialNumber)
         new_scope_sns -= sns_to_unassign
 
-        update_scope(prestage_name, spath, new_scope_sns, scope.versionLock, cnx)
+        update_scope(spath, new_scope_sns, scope.versionLock, cnx)
       end # self.unassign
 
-      # Private Class Methods
-      #####################################
+      # the endpoint path for the scope of a given prestage id
+      #
+      def scope_path(prestage_id = nil)
+        pfx = defined?(self::SCOPE_PATH_PREFIX) ? self::SCOPE_PATH_PREFIX : get_path
 
-      # the class level scope path for a given prestage id
-      def scope_path(prestage_id)
-        "#{self::LIST_PATH}/#{prestage_id}/#{SCOPE_PATH}"
+        prestage_id ? "#{pfx}/#{prestage_id}/#{SCOPE_PATH}" : "#{pfx}/#{SCOPE_PATH}"
       end
-      private :scope_path
+
+      # Private Class Methods
+      #####################################
 
       # used by assign and unassign
-      def update_scope(prestage_name, spath, new_scope_sns, vlock, cnx)
+      def update_scope(spath, new_scope_sns, vlock, cnx)
         assignment_data = {
           serialNumbers: new_scope_sns,
           versionLock: vlock
@@ -272,34 +245,29 @@ module Jamf
     # Instance Methods
     #####################################
 
-    # The scope data for this prestage
-    #
-    # TODO: retain this caching?
+    # The scope data for this prestage -
     #
-    # @param refresh[Boolean] reload fromthe API?
+    # @param refresh[Boolean] reload from the API? DEPRECATED:
+    #   the data is always read from the API. If making many calls at once,
+    #   consisider capturing the data in your own variable
     #
     # @return [PrestageScope]
     #
-    def scope(refresh: false)
-      @scope = nil if refresh
-      return @scope if @scope
+    def scope(refresh = false) # rubocop:disable Lint/UnusedMethodArgument
+      scope = INSTANCE_SCOPE_OBJECT.new @cnx.get(scope_path)
 
-      @scope = INSTANCE_SCOPE_OBJECT.new @cnx.get(scope_path)
       # TODO: is this the best way to deal with fetching a scope that
       # is more updated than the rest of the object?
-      unless @scope.versionLock == @versionLock
-        raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again"
+      unless scope.versionLock == @versionLock
+        raise Jamf::VersionLockError, "The #{self.class} '#{displayName}' has been modified since it was fetched. Please refetch and try again"
       end
 
-      @scope
+      scope
     end
 
     # @return [Array<String>] the serialnumbers assigned to this prestage
-    def assigned_sns(refresh: false)
-      return @assigned_sns if @assigned_sns
-
-      @assigned_sns = nil if refresh
-      @assigned_sns = scope.assignments.map(&:serialNumber)
+    def assigned_sns
+      scope.assignments.map(&:serialNumber)
     end
 
     # Is this SN assigned to this prestage?
@@ -315,40 +283,24 @@ module Jamf
       assigned_sns.include? sn
     end
     alias include? assigned?
+    alias scoped? assigned?
 
     # Assign
     def assign(*sns_to_assign)
-      @scope = self.class.assign(sns_to_assign, to_prestage: @id, cnx: @cnx)
-      @versionLock = @scope.versionLock
-
-      # sns_to_assign.map!(&:to_s)
-      # new_scope_sns = assigned_sns
-      # new_scope_sns += sns_to_assign
-      # new_scope_sns.uniq!
-      # update_scope(new_scope_sns)
+      scope = self.class.assign(*sns_to_assign, to_prestage: @id, cnx: @cnx)
+      @versionLock = scope.versionLock
     end
     alias add assign
 
     def unassign(*sns_to_unassign)
-      @scope = self.class.unassign(sns_to_unassign, from_prestage: @id, cnx: @cnx)
-      @versionLock = @scope.versionLock
-      # sns_to_unassign.map!(&:to_s)
-      # new_scope_sns = assigned_sns
-      # new_scope_sns -= sns_to_unassign
-      # update_scope(new_scope_sns)
+      scope = self.class.unassign(*sns_to_unassign, from_prestage: @id, cnx: @cnx)
+      @versionLock = scope.versionLock
     end
     alias remove unassign
 
-    def save
-      super
-      # the scope needs to be refreshed, since its versionLock will need to be
-      # updated
-      @scope = nil
-    end
-
     # The scope endpoint for this instance
     def scope_path
-      @scope_path ||= "#{get_path}/#{SCOPE_PATH}"
+      @scope_path ||= self.class.scope_path(id)
     end
 
   end # class

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -36,7 +36,7 @@ module Jamf
     #   Settings for Account Driven User Enrollment. Only 1 of expirationIntervalDays or expirationIntervalSeconds can be supplied.
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.

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

@@ -35,7 +35,7 @@ module Jamf
     #
     #
     # This class was automatically genereated from the api/schema
-    # URL path on a Jamf Pro server version 10.46.0-t1681398190
+    # URL path on a Jamf Pro server version 10.50.0-t1693149930
     #
     # 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.