ruby-jss 1.2.3 → 1.2.4a1

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

@@ -0,0 +1,111 @@
+# Copyright 2019 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
+
+  class Connection
+
+    # TODO: figure out what to do with
+    # ConflictError, BadRequestError, APIRequestError
+    # and maybe AuthenticationError
+    class APIError < RuntimeError
+
+      RSRC_NOT_FOUND = 'Resource Not Found'.freeze
+
+      # Struct to hold the info for each individual error in an API error
+      # response body.
+      #
+      # Has these attributes (descriptions from developer.jamf.com):
+      #
+      # code: String
+      #   Error-specific code that can be used to identify localization
+      #   string, etc.
+      #
+      # field: String
+      #   Name of the field that caused the error.
+      #
+      # description: String
+      #   A general description of error for troubleshooting/debugging.
+      #   Generally this text should not be displayed to a user; instead
+      #   refer to errorCode and its localized text
+      #
+      # id: Integer
+      #   id of object with error. 0 if not applicable
+      #
+      ErrorInfo = ImmutableStruct.new(:code, :field, :description, :id) do
+        def to_s
+          deets = "{code: #{code}"
+          deets << ", field: #{field}" if field
+          deets << ", id: #{id}" if id
+          deets << '}'
+          "#{description} #{deets}"
+        end
+      end # ErrorInfo
+
+      # @return [Faraday::Response]
+      attr_reader :http_response
+
+      # @return [integer]
+      #
+      attr_reader :httpStatus
+      alias status httpStatus
+
+      # @return [Array<ErrorInfo>] see  ErrorInfo above
+      #
+      attr_reader :errors
+
+      # @return [RestClient::ExceptionWithResponse] the original RestClient error
+      attr_reader :rest_error
+
+      # @param rest_error [RestClient::ExceptionWithResponse]
+      def initialize(http_response)
+        @http_response = http_response
+        @httpStatus = http_response.status
+
+        @errors =
+          if @http_response.body.dig :errors
+            @http_response.body[:errors].map { |e| ErrorInfo.new e }
+          else
+            []
+          end
+
+        if @errors.empty?
+          code = @httpStatus
+          desc = @httpStatus == 404 ? RSRC_NOT_FOUND : @http_response.reason_phrase
+          @errors << ErrorInfo.new(code: code, field: nil, description: desc, id: nil)
+        end
+
+        super
+      end
+
+      def to_s
+        @errors.map(&:to_s).join '; '
+      end
+
+    end # class APIError
+
+  end # class Connection
+
+end # module JSS

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

@@ -0,0 +1,96 @@
+# Copyright 2019 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
+
+  # When the API returns an HTTP status other than 2xx or 3xx, the document body
+  # contains one of these.
+  #
+  class APIError < Jamf::JSONObject
+
+    OBJECT_MODEL = {
+
+      # @!attribute [r] traceId
+      #   @return [String]
+      traceId: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] errors
+      #   @return [Array<Jamf::APIErrorDetail>]
+      errors: {
+        class: Jamf::APIErrorDetail,
+        readonly: true,
+        multi: true
+      }
+
+    }.freeze
+
+    parse_object_model
+
+  end # class APIError
+
+  # an individual error report in an APIError object
+  class APIErrorDetail < Jamf::JSONObject
+
+    OBJECT_MODEL = {
+
+      # @!attribute [r] objectId
+      #   @return [String]
+      objectId: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] reasonCode
+      #   @return [String]
+      reasonCode: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] field
+      #   @return [String]
+      field: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] description
+      #   @return [String]
+      description: {
+        class: :string,
+        readonly: true
+      }
+
+    }.freeze
+
+    parse_object_model
+
+  end # class APIErrorDetail
+
+end # module

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

@@ -0,0 +1,220 @@
+# Copyright 2019 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
+
+  class Connection
+
+    # A token used for a JSS connection
+    class Token
+
+      AUTH_RSRC = 'auth'.freeze
+
+      NEW_TOKEN_RSRC = "#{AUTH_RSRC}/tokens".freeze
+
+      KEEP_ALIVE_RSRC = "#{AUTH_RSRC}/keepAlive".freeze
+
+      INVALIDATE_RSRC = "#{AUTH_RSRC}/invalidateToken".freeze
+
+      # this string is prepended to the token data when used for
+      # transaction authorization.
+      AUTH_TOKEN_PFX = 'jamf-token '.freeze
+
+      # @return [String] The user who generated this token
+      attr_reader :user
+
+      # @return [Jamf::Timestamp]
+      attr_reader :expires
+      alias expiration expires
+
+      # @return [String] The AUTH_TOKEN_PFX with the token data, used in the
+      #   Authorization header of a request
+      attr_reader :auth_token
+
+      # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/uapi
+      attr_reader :base_url
+
+      # when was this token created?
+      attr_reader :login_time
+
+      def initialize(**params)
+        @valid = false
+        @user = params[:user]
+        @base_url = params[:base_url].is_a?(String) ? URI.parse(params[:base_url]) : params[:base_url]
+        @timeout = params[:timeout] || Jamf::Connection::DFT_TIMEOUT
+        @ssl_options = params[:ssl_options] || {}
+
+        if params[:pw]
+          init_from_pw params[:pw]
+        elsif params[:token_string]
+          init_from_token_string params[:token_string]
+        else
+          raise ArgumentError, 'Must provide either pw: or token_string:'
+        end
+
+      end # init
+
+      # Initialize from password
+      def init_from_pw(pw)
+        resp = token_connection(
+          NEW_TOKEN_RSRC,
+          pw: pw,
+          timeout: @timeout,
+          ssl_opts: @ssl_options
+        ).post
+
+        if  resp.success?
+          parse_token_from_response resp
+        elsif resp.status == 401
+          raise Jamf::AuthenticationError, 'Incorrect name or password'
+        else
+          # TODO: better error reporting here
+          raise 'An error occurred while authenticating'
+        end
+      end # init_from_pw
+
+      # Initialize from token string
+      def init_from_token_string(str)
+        str = "#{AUTH_TOKEN_PFX}#{str}" unless str.start_with? AUTH_TOKEN_PFX
+        resp = token_connection(AUTH_RSRC, token: str).get
+        raise Jamf::InvalidDataError, 'Token string is not valid' unless resp.success?
+
+        @auth_token = str
+        @user = resp.body.dig :account, :username
+        # use this token to get a fresh one with a known expiration
+        keep_alive
+      end # init_from_token_string
+
+      # @return [String]
+      def host
+        @base_url.host
+      end
+
+      # @return [Integer]
+      def port
+        @base_url.port
+      end
+
+      # @return [String]
+      def api_version
+        token_connection(Jamf::Connection::SLASH, token: @auth_token ).get.body[:version]
+      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
+
+      # @return [Boolean]
+      def valid?
+        @valid =
+          if expired?
+            false
+          elsif !@auth_token
+            false
+          else
+            token_connection(AUTH_RSRC, token: @auth_token).get.success?
+          end
+      end
+
+      # 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
+      end
+
+      # Use this token to get a fresh one
+      def keep_alive
+        raise 'Token has expired' if expired?
+
+        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?
+
+        parse_token_from_response keep_alive_token_resp
+        # parse_token_from_response keep_alive_rsrc.post('')
+        expires
+      end
+      alias refresh keep_alive
+
+      # Make this token invalid
+      def invalidate
+        @valid = !token_connection(INVALIDATE_RSRC, token: @auth_token).post.success?
+      end
+      alias destroy invalidate
+
+      # Private instance methods
+      #################################
+      private
+
+      # 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|
+          con.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_JSON
+          con.response :json, parser_options: { symbolize_names: true }
+          con.options[:timeout] = timeout
+          con.options[:open_timeout] = timeout
+          if token
+            con.headers[:authorization] = token
+          else
+            con.basic_auth @user, pw
+          end
+          con.use Faraday::Adapter::NetHttp
+        end # Faraday.new
+      end # token_connection
+
+      # Parse the API token data into instance vars.
+      def parse_token_from_response(resp)
+        @token_response_body = resp.body
+        @auth_token = AUTH_TOKEN_PFX + @token_response_body[:token]
+        @expires = Jamf::Timestamp.new @token_response_body[:expires]
+        @login_time = Jamf::Timestamp.new Time.now
+        @valid = true
+      end
+
+    end # class Token
+
+  end # class Connection
+
+end # module JSS

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

@@ -0,0 +1,79 @@
+# Copyright 2019 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
+  #####################################
+
+  # Preferences for an administrator account in the JSS
+  class AccountPreferences < Jamf::JSONObject
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = {
+
+      # @!attribute [r] language
+      #   @return [String]
+      language: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] dateFormat
+      #   @return [String]
+      dateFormat: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] region
+      #   @return [String]
+      region: {
+        class: :string,
+        readonly: true
+      },
+      # @!attribute [r] timezone
+      #   @return [String]
+      timezone: {
+        class: :string,
+        readonly: true
+      },
+
+      # @!attribute [r] isDisableRelativeDates
+      #   @return [String]
+      isDisableRelativeDates: {
+        class: :boolean,
+        readonly: true
+      }
+    }.freeze
+    parse_object_model
+
+  end # class
+
+end # module