ruby-jss 1.2.4a3 → 1.3.2

data/lib/jamf/api/connection/api_error.rb

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

data/lib/jamf/api/connection/api_error_styleguide.rb

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

data/lib/jamf/api/connection/token.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -30,6 +30,8 @@ module Jamf
     # A token used for a JSS connection
     class Token
 
+      JAMF_VERSION_RSRC = 'v1/jamf-pro-version'.freeze
+
       AUTH_RSRC = 'auth'.freeze
 
       NEW_TOKEN_RSRC = "#{AUTH_RSRC}/tokens".freeze
@@ -56,9 +58,22 @@ module Jamf
       # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/uapi
       attr_reader :base_url
 
-      # when was this token created?
+      # @return [Jamf::Timestamp] when was this token created?
       attr_reader :login_time
 
+      # What happened the last time we tried to refresh?
+      #   :expired_refreshed - token was expired, a new token was created with the pw
+      #   :expired_pw_failed - token was expired, pw failed to make a new token
+      #   :expired_no_pw - token was expired, but no pw was given to make a new one
+      #   :refreshed - the token refresh worked with no need for the pw
+      #   :refresh_failed - the token refresh failed, and no pw was given to make a new one
+      #   :refreshed_with_pw - the token refresh failed, pw worked to make a new token
+      #   :refresh_failed_no_pw - the token refresh failed, pw also failed to make a new token
+      #   nil - no refresh has been attempted for this token.
+      #
+      # @return [Symbol, nil] :refreshed, :pw, :expired,:failed, or nil if never refreshed
+      attr_reader :last_refresh_result
+
       def initialize(**params)
         @valid = false
         @user = params[:user]
@@ -90,7 +105,7 @@ module Jamf
           raise Jamf::AuthenticationError, 'Incorrect name or password'
         else
           # TODO: better error reporting here
-          raise 'An error occurred while authenticating'
+          raise Jamf::AuthenticationError, 'An error occurred while authenticating'
         end
       end # init_from_pw
 
@@ -118,25 +133,33 @@ module Jamf
       end
 
       # @return [String]
-      def api_version
-        token_connection(Jamf::Connection::SLASH, token: @auth_token ).get.body[:version]
+      def jamf_version
+        raw_jamf_version.split('-').first
+      end
+
+      # @return [String]
+      def jamf_build
+        raw_jamf_version.split('-').last
       end
 
       # @return [Boolean]
       def expired?
         return unless @expires
+
         Time.now >= @expires
       end
 
       # @return [Float]
       def secs_remaining
         return unless @expires
+
         @expires - Time.now
       end
 
       # @return [String] e.g. "1 week 6 days 23 hours 49 minutes 56 seconds"
       def time_remaining
         return unless @expires
+
         Jamf.humanize_secs secs_remaining
       end
 
@@ -155,23 +178,46 @@ module Jamf
       # the Jamf::Account object assciated with this token
       def account
         return @account if @account
+
         resp = token_connection(AUTH_RSRC, token: @auth_token).get
         return unless resp.success?
 
-         @account = Jamf::APIAccount.new resp.body
+        @account = Jamf::APIAccount.new resp.body
       end
 
-      # Use this token to get a fresh one
-      def refresh
-        raise 'Token has expired' if expired?
+      # Use this token to get a fresh one. If a pw is provided
+      # try to use it to get a new token if a proper refresh fails.
+      #
+      # @param pw [String] Optional password to use if token refresh fails.
+      #   Must be the correct passwd or the token's user (obviously)
+      #
+      # @return [Jamf::Timestamp] the new expiration time
+      #
+      def refresh(pw = nil)
+        # gotta have a pw if expired
+        if expired?
+          # try the passwd
+          return refresh_with_passwd(pw, :expired_refreshed, :expired_pw_failed) if pw
+
+          # no passwd? no chance!
+          @last_refresh_result = :expired_no_pw
+          raise Jamf::InvalidTokenError, 'Token has expired'
+        end
 
+        # Now try a normal refresh of our non-expired token
         keep_alive_token_resp = token_connection(KEEP_ALIVE_RSRC, token: @auth_token).post
-        # TODO: better error reporting here
-        raise 'An error occurred while authenticating' unless keep_alive_token_resp.success?
+        if keep_alive_token_resp.success?
+          parse_token_from_response keep_alive_token_resp
+          @last_refresh_result = :refreshed
+          return expires
+        end
 
-        parse_token_from_response keep_alive_token_resp
-        # parse_token_from_response keep_alive_rsrc.post('')
-        expires
+        # if we're here, the normal refresh failed, so try the pw
+        return refresh_with_passwd(pw, :refreshed_with_pw, :refresh_failed_no_pw) if pw
+
+        # if we're here, no pw? no chance!
+        @last_refresh_result = :refresh_failed
+        raise 'An error occurred while refreshing the token' unless pw
       end
       alias keep_alive refresh
 
@@ -185,12 +231,37 @@ module Jamf
       #################################
       private
 
+      # refresh a token using a password, return a result
+      # @param pw[String] the password to use
+      # @return [JamfTimestamp] the new expiration
+      def refresh_with_passwd(pw, success, failure)
+        init_from_pw(pw)
+        @last_refresh_result = success
+        expires
+      rescue => e
+        @last_refresh_result = failure
+        raise e, "#{e}. Status: :#{failure}"
+      end
+
+      # @return [String]
+      def raw_jamf_version
+        # TODO: Remove this once we require Jamf Pro 10.19 and up
+        # the rsrc for getting the version used to be nothing (the
+        # base url itself returnedit) but now its JAMF_VERSION_RSRC
+        resp = token_connection(Jamf::BLANK, token: @auth_token).get # .body # [:version]
+        return resp.body[:version] if resp.success?
+
+        resp = token_connection(JAMF_VERSION_RSRC, token: @auth_token).get
+        return resp.body[:version] if resp.success?
+
+        raise Jamf::InvalidConnectionError, 'Unable to read Jamf version from the API'
+      end
+
       # a generic, one-time Faraday connection for token
       # acquision & manipulation
       #
       def token_connection(rsrc, token: nil, pw: nil, timeout: nil, ssl_opts: nil)
-
-        Faraday.new("#{@base_url}/#{rsrc}", ssl: ssl_opts ) do |con|
+        Faraday.new("#{@base_url}/#{rsrc}", ssl: ssl_opts) do |con|
           con.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_JSON
           con.response :json, parser_options: { symbolize_names: true }
           con.options[:timeout] = timeout

data/lib/jamf/api/json_objects/account_prefs.rb

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

data/lib/jamf/api/json_objects/android_details.rb

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

data/lib/jamf/api/json_objects/appletv_details.rb

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

data/lib/jamf/api/json_objects/attachment.rb

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

data/lib/jamf/api/json_objects/cellular_network.rb

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

data/lib/jamf/api/json_objects/change_log_entry.rb

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

data/lib/jamf/api/json_objects/computer_prestage_skip_setup_items.rb

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

data/lib/jamf/api/json_objects/country.rb

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

data/lib/jamf/api/json_objects/criterion.rb

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

data/lib/jamf/api/json_objects/device_enrollment_device.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -77,10 +77,13 @@ module Jamf
       # @!attribute deviceEnrollmentProgramInstanceId
       #   @return [Integer]
       deviceEnrollmentProgramInstanceId: {
-        class: :integer
+        class: :integer,
+        aliases: %i[instanceId]
       },
 
       # @!attribute prestageId
+      #   The most recent prestage this device was assigned to, even if
+      #   currently unassigned to any prestage.
       #   @return [Integer]
       prestageId: {
         class: :integer
@@ -135,6 +138,7 @@ module Jamf
       },
 
       # @!attribute deviceAssignedDate
+      #   When Apple assigned this device to this DevEnrollment instance
       #   @return [Jamf::Timestamp]
       deviceAssignedDate: {
         class: Jamf::Timestamp
@@ -146,8 +150,6 @@ module Jamf
     # Class Methods
     #########################################
 
-
-
     # Instance Methods
     #########################################
 

data/lib/jamf/api/json_objects/device_enrollment_sync_status.rb

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

data/lib/jamf/api/json_objects/extension_attribute_value.rb

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

data/lib/jamf/api/json_objects/installed_application.rb

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

data/lib/jamf/api/json_objects/installed_certificate.rb

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

data/lib/jamf/api/json_objects/installed_configuration_profile.rb

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

data/lib/jamf/api/json_objects/installed_ebook.rb

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

data/lib/jamf/api/json_objects/installed_provisioning_profile.rb

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

data/lib/jamf/api/json_objects/inventory_preload_extension_attribute.rb

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

data/lib/jamf/api/json_objects/ios_details.rb

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

data/lib/jamf/api/json_objects/location.rb

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

data/lib/jamf/api/json_objects/md_prestage_name.rb

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

data/lib/jamf/api/json_objects/md_prestage_names.rb

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

data/lib/jamf/api/json_objects/md_prestage_skip_setup_items.rb

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

data/lib/jamf/api/json_objects/mobile_device_details.rb

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

data/lib/jamf/api/json_objects/mobile_device_security.rb

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

data/lib/jamf/api/json_objects/prestage_assignment.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -26,7 +26,8 @@
 # The module
 module Jamf
 
-  # A 'location' for a managed object in Jamf Pro
+  # An assignment of a device to a prestage, placing that
+  # device into the prestage's scope
   class PrestageAssignment < Jamf::JSONObject
 
     extend Jamf::Immutable
@@ -48,7 +49,8 @@ module Jamf
       # @!attribute userAssigned
       #   @return [String]
       userAssigned: {
-        class: :string
+        class: :string,
+        aliases: %i[assignedBy]
       }
     }.freeze
 

data/lib/jamf/api/json_objects/prestage_location.rb

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

data/lib/jamf/api/json_objects/prestage_purchasing_data.rb

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

data/lib/jamf/api/json_objects/prestage_scope.rb

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

data/lib/jamf/api/json_objects/prestage_sync_status.rb

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