ruby-jss 1.6.0 → 2.0.0a11

data/lib/jamf/api/base_classes/resource.rb

@@ -1,259 +0,0 @@
-# Copyright 2020 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
-  #####################################
-
-  # @see_also Jamf::JSONObject
-  #
-  # Jamf::Resource represents a thing directly accessible in the API. It
-  # will contain one or more API endpoints.
-  #
-  # A resource has a base URI path in the API used for
-  # interacting with the resource and directly-related sub-resources.
-  #
-  # For example, the device-reenrollment settings are a resource at the url path
-  #
-  # >  .../uapi/v1/reenrollment
-  #
-  # and the related sub-resource for the change history of the reenrollment
-  # settings is at
-  #
-  # > .../uapi/v1/reenrollment/history
-  #
-  # All resources based at .../uapi/v1/reenrollment are encapsulated
-  # in the class {Jamf::ReEnrollmentSettings}, a descendent of Jamf::Resource
-  #
-  # There are two types of resources: Singletons and Collections.
-  #
-  # **Singleton resources** have only one instance available in the API, and they
-  # cannot be create or deleted, only fetched and usually updated, tho some cant
-  # be updated either, e.g. Jamf::AppStoreCountryCodes. The device-reenrollment
-  # settings mentioned above are an example of a Singleton resource.
-  # When the resource is fetched from the API, it is cached, and (usually) future
-  # fetching will return the same instance. See {Jamf::SingletonResource} for
-  # details.
-  #
-  # **Collection resources** have more than one resource within them, and those
-  # can (usually) be created and deleted as well as fetched and updated.
-  # The entire collection (or a part of it) can also be fetched as an Array.
-  # When the whole collection is fetched, the result is cached for future use.
-  # See {Jamf::CollectionResource} for details.
-  #
-  # # Instantiating Resources
-  #
-  # For all subclasses of Jamf::Resource, using the ruby standard .new class
-  # method to instantiate an object will raise an exception. We do this to avoid
-  # the ambiguity of the word 'new' in this context.
-  #
-  # Normally in ruby, .new means 'make a new instance of this class in memory'.
-  # But with Jamf Resoureces, when making a new instance in memory, we might be
-  # making an instance of a resource that already exists in Jamf Pro, or perhaps
-  # making an instance of a 'new' thing that we want to create in Jamf Pro,
-  # but doesn't exist there at the moment.
-  #
-  # While we could look at the parameters passed to decide which of those two
-  # things we're doing, (and require specific parameters for each action), that
-  # doesn't change the fact that a human _reading_ the line:
-  #
-  #   a_building = Jamf::Building.new name: 'Main Building'
-  #
-  # sounds like we want to create a new building in the JSS, when in fact we're
-  # just retrieving one that's already there.
-  #
-  # To make the code more readable and totally clear, .new is not allowed for
-  # making instances of Jamf::Resources. Instead, use the class method .fetch
-  # to retrieve existing resources, like so:
-  #
-  #   a_building = Jamf::Building.fetch name: 'Main Building'
-  #
-  # This makes it clear what the code is doing, and when you get the error that
-  # there's no building with that name, the error makes sense, which it
-  # wouldn't if you were creating a new building in the JSS.
-  #
-  # Likewise, to make a new one in Jamf Pro, use .create, as in:
-  #
-  #   a_building = Jamf::Building.create name: 'Main Building'
-  #
-  # This makes it obvious that we're creating a new building in the JSS
-  #
-  # In both cases, the instance method #save is used to send your changes to the
-  # API. If the resource already exists, the changes will be applied to the
-  # server with #save.  If it doesn't yet exist, it will be created by #save.
-  #
-  #
-  # # Subclassing
-  #
-  #
-  # ### Required Constant: RSRC_VERSION
-  #
-  # The version of the resource model supported by ruby-jss for this class.
-  #
-  # Every resource in the Jamf Pro API has a version as part of its URL path.
-  # For example, in the full resource URL:
-  #
-  #    https://your.jamf.server:port/uapi/v1/reenrollment
-  #
-  # the resource version is `v1`.  At any given time, the API may have many
-  # versions of a resource available - v2 might be released with new values
-  # available or deprecated values removed, but v1 remains and is unchanged.
-  #
-  # Each subclass of Jamf::Resource must define RSRC_VERSION as a
-  # String, e.g. 'v1', which defines the version supported by the subclass.
-  #
-  # As new versions are released by Jamf, when the changes are implemented
-  # in ruby-jss, the RSRC_VERSION is updated.
-  #
-  # ## Required Constant: OBJECT_MODEL
-  #
-  # This is required of all {Jamf::JSONObject} subclasses. Refer to that
-  # documentation for full details about implementing the OBJECT_MODEL constant.
-  #
-  # ## Required Constant: RSRC_PATH
-  #
-  # This is the URI path to the resource, relative to the API base and version
-  # ('uapi/vX/').
-  #
-  # Examples:
-  #
-  #   1. For SingletonResource class {Jamf::Settings::ReEnrollment}, the URL to
-  #      the resource is:
-  #
-  #         https://your.jamf.server:port/uapi/v1/reenrollment
-  #
-  #      and that URL is used to GET and PUT data, and as a base for the change
-  #      log data.
-  #
-  #      The constant {Jamf::Settings::ReEnrollment::RSRC_PATH} must be
-  #      `'reenrollment'`
-  #
-  #   2. For CollectionResource class {Jamf::MobileDevice}, the URL to the
-  #      collection Array is:
-  #
-  #         https://your.jamf.server:port/uapi/v1/mobile-devices
-  #
-  #      and that URL is used to GET lists of mobileDevice data and POST data
-  #      to create a new mobile device.
-  #      It is also the base URL for GET, PATCH, PUT and DELETE for individual
-  #      mobileDevices, and their details and change log data.
-  #
-  #      The constant {Jamf::MobileDevice::RSRC_PATH} must be
-  #      `'mobile-devices'`
-  #
-  # ## Required Constant: RSRC_VERSION
-  #
-  # As shown in the examples above, the URL paths for resources have a
-  # version number between 'uapi' and the RSRC_PATH
-  #
-  # Both SingletonResources and CollectionResources must defing the constant
-  # RSRC_VERSION as a string containing that version, e.g. 'v1'
-  #
-  # ruby-jss doesn't support the older resource paths that don't have a version
-  # in their path.
-  #
-  # @abstract
-  #
-  class Resource < Jamf::JSONObject
-
-    extend Jamf::BaseClass
-
-    # Constants
-    #####################################
-
-    # These methods are allowed to call .new
-    NEW_CALLERS = ['fetch', 'create', 'all', 'cached_all', 'block in all', 'block in cached_all'].freeze
-
-    # The resource version for previewing new features
-    RSRC_PREVIEW_VERSION = 'preview'.freeze
-
-    # Public Class Methods
-    #####################################
-
-    # the resource path for this resource
-    # @return [String]
-    def self.rsrc_path
-      @rsrc_path ||= "#{self::RSRC_VERSION}/#{self::RSRC_PATH}"
-    end
-
-    def self.preview_path
-      "#{RSRC_PREVIEW_VERSION}/#{self::RSRC_PATH}"
-    end
-
-    # Disallow direct use of ruby's .new class method for creating instances.
-    # Require use of .fetch or .create, or 'all'
-    #
-    def self.new(data, cnx: Jamf.cnx)
-      stop_if_base_class
-      calling_method = caller_locations(1..1).first.label
-      raise Jamf::UnsupportedError, "Use .fetch, .create, or .all(instantiate:true) to instantiate Jamf::Resources" unless NEW_CALLERS.include? calling_method
-      super
-    end
-
-    # Attributes
-    #####################################
-
-    # @return [Jamf::Connection] the API connection thru which we deal with
-    #   this resource.
-    attr_reader :cnx
-
-    # @return [String] the resouce path for this object
-    attr_reader :rsrc_path
-
-    # Instance Methods
-    #####################################
-
-    # TODO: error handling
-    def save
-      raise Jamf::UnsupportedError, "#{self.class} objects cannot be changed" unless self.class.mutable?
-
-      return unless unsaved_changes?
-
-      exist? ? update_in_jamf : create_in_jamf
-      clear_unsaved_changes
-
-      @id || :saved
-    end
-
-    # Private Instance Methods
-    #####################################
-    private
-
-    # TODO: handle PATCH when it becomes a thing
-    def update_in_jamf
-      @cnx.put(rsrc_path, to_jamf)
-    rescue Jamf::Connection::APIError => e
-      if e.status == 409 && self.class.included_modules.include?(Jamf::Lockable)
-        raise Jamf::VersionLockError, "The #{self.class} has been modified since it was fetched. Please refetch and try again."
-      end
-
-      raise e
-    end
-
-  end # class APIObject
-
-end # module JAMF

data/lib/jamf/api/base_classes/singleton_resource.rb

@@ -1,88 +0,0 @@
-# Copyright 2020 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
-  #####################################
-
-  # A Singleton Resource in the API.
-  #
-  # See {Jamf::Resource} for details and required constants
-  #
-  # @abstract
-  #
-  class SingletonResource < Jamf::Resource
-
-    extend Jamf::BaseClass
-
-    # Public Class Methods
-    #####################################
-
-    # Return a SingletonResource from the API, from the cache if already cached
-    # or retrieving from the API and caching it if neededl
-    #
-    # @param reload[Boolean] If already cached, re-cache from the API.
-    #   WARNING: unsaved changes will be lost.
-    #
-    # @param version[String] the API resource version to use.
-    #   Defaults to the RSRC_VERSION for the class.
-    #
-    # @param cnx[Jamf::Connection] The API connection to use
-    #
-    # @return [Jamf::SingletonResource] The ruby-instance of a Jamf resource
-    #
-    def self.fetch(reload = false, cnx: Jamf.cnx)
-      stop_if_base_class
-      cnx.singleton_cache[self] = nil if reload
-      cached = cnx.singleton_cache[self]
-      return cached if cached
-
-      data = cnx.get rsrc_path
-      cnx.singleton_cache[self] = new data, cnx: cnx
-    end # fetch
-
-    def self.flushcache(cnx: Jamf.cnx)
-      stop_if_base_class
-      cnx.singleton_cache[self] = nil
-    end
-
-    # Instance Methods
-    #####################################
-
-    # only have one path
-    def rsrc_path
-      self.class.rsrc_path
-    end
-
-    # singltons always exist
-    def exist?
-      true
-    end
-
-  end # class APIObject
-
-end # module JAMF

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

@@ -1,111 +0,0 @@
-# Copyright 2020 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.is_a? String
-            JSON.parse(@http_response.body)[:errors]
-          elsif @http_response.body.is_a?(Hash)
-            @http_response.body[:errors]
-          end
-        @errors &&= @errors.map { |e| ErrorInfo.new e }
-
-        unless @errors
-          code = @httpStatus
-          desc = code == 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

@@ -1,96 +0,0 @@
-# Copyright 2020 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/json_objects/change_log_entry.rb

@@ -1,77 +0,0 @@
-# Copyright 2020 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
-
-  # A single entry in a resource's change history.
-  # This class is read-only
-  #
-  class ChangeLogEntry < Jamf::JSONObject
-
-    extend Jamf::Immutable
-
-    OBJECT_MODEL = {
-
-      # @!attribute [r] id
-      #  @return [String] The Jamf Pro user who made the change or note.
-      id: {
-        class: :integer,
-        readonly: true
-      },
-
-      # @!attribute [r] username
-      #  @return [String] The Jamf Pro user who made the change or note.
-      username: {
-        class: :string,
-        readonly: true
-      },
-
-      # @!attribute [r] date
-      #  @return [Jamf::Timestamp] When the change was made
-      date: {
-        class: Jamf::Timestamp,
-        readonly: true
-      },
-
-      # @!attribute [r] notes
-      #  @return [String] Notes entered manually or via the API.
-      note: {
-        class: :string,
-        readonly: true
-      },
-
-      # @!attribute [r] details
-      #  @return [String] Details of the change
-      details: {
-        class: :string,
-        readonly: true
-      }
-    }.freeze
-
-    # Must call parse_object_model to turn the OBJECT_MODEL into
-    # attributes
-    parse_object_model
-
-  end # class
-
-end # module

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

@@ -1,51 +0,0 @@
-# Copyright 2020 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
-
-  # A 'location' for a managed object in Jamf Pro
-  class Country < Jamf::JSONObject
-
-    OBJECT_MODEL = {
-
-      # @!attribute code [r]
-      #   @return [String] the country code
-      code: {
-        class: :string
-      },
-
-      # @!attribute name [r]
-      #   @return [String] the country name
-      name: {
-        class: :string
-      }
-    }.freeze
-
-    parse_object_model
-
-  end # class Country
-
-end # module