ruby-jss 1.6.4 → 2.0.0a10

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

@@ -0,0 +1,124 @@
+# Copyright 2022 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: VppTokenSubscription
+    #
+    #
+    #
+    # This class was automatically genereated from the api/schema
+    # URL path on a Jamf Pro server version 10.36.1-t1645562643
+    #
+    # 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.
+    #  
+    #
+    # Sub Objects:
+    # Other object models used by this model's attributes.
+    #  - Jamf::OAPISchemas::Recipients
+    #  - Jamf::OAPISchemas::AdminAccount
+    #
+    # Endpoints and Privileges:
+    # API endpoints and HTTP operations that use this object
+    # model, and the Jamf Pro privileges needed to access them.
+    #  - '/vpp/subscriptions:GET' needs permissions:
+    #    - Read Volume Purchasing Administrator Accounts
+    #  - '/vpp/subscriptions/{id}:GET' needs permissions:
+    #    - Read Volume Purchasing Administrator Accounts
+    #
+    #
+    class VppTokenSubscription < Jamf::OAPIObject
+
+      
+
+      OAPI_PROPERTIES = {
+
+        # @!attribute id
+        #   @return [Integer]
+        id: {
+          class: :j_id,
+          identifier: :primary
+        },
+
+        # @!attribute name
+        #   @return [String]
+        name: {
+          class: :string
+        },
+
+        # @!attribute enabled
+        #   @return [Boolean]
+        enabled: {
+          class: :boolean
+        },
+
+        # @!attribute recipients
+        #   @return [Jamf::OAPISchemas::Recipients]
+        recipients: {
+          class: Jamf::OAPISchemas::Recipients
+        },
+
+        # @!attribute adminAccounts
+        #   @return [Array<Jamf::OAPISchemas::AdminAccount>]
+        adminAccounts: {
+          class: Jamf::OAPISchemas::AdminAccount,
+          multi: true
+        },
+
+        # @!attribute siteID
+        #   @return [Integer]
+        siteID: {
+          class: :integer
+        },
+
+        # @!attribute siteName
+        #   @return [String]
+        siteName: {
+          class: :string
+        }
+
+      } # end OAPI_PROPERTIES
+
+    end # class VppTokenSubscription
+
+  end # module OAPISchemas
+
+end # module Jamf

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

@@ -0,0 +1,88 @@
+# Copyright 2022 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: WebLink
+    #
+    #
+    #
+    # This class was automatically genereated from the api/schema
+    # URL path on a Jamf Pro server version 10.36.1-t1645562643
+    #
+    # 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.
+    #  
+    #
+    # 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 WebLink < Jamf::OAPIObject
+
+      
+
+      OAPI_PROPERTIES = {
+
+        # @!attribute name
+        #   @return [String]
+        name: {
+          class: :string
+        },
+
+        # @!attribute url
+        #   @return [String]
+        url: {
+          class: :string
+        }
+
+      } # end OAPI_PROPERTIES
+
+    end # class WebLink
+
+  end # module OAPISchemas
+
+end # module Jamf

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

@@ -0,0 +1,35 @@
+# Copyright 2022 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
+
+  # This module is the namespace for all objects defined
+  # in the OAPI JSON schema under the components => schemas key
+  #####################################
+  module OAPISchemas
+
+  end # module OAPISchemas
+
+end # module Jamf

data/lib/{jss/ruby_extensions/string.rb → jamf/api/jamf_pro/other_classes/change_log_entry.rb}

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -20,16 +20,18 @@
 #    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
 
-require 'jss/ruby_extensions/string/conversions.rb'
-require 'jss/ruby_extensions/string/predicates.rb'
-require 'jss/ruby_extensions/string/backports.rb'
+  # A wrapper around Jamf::OAPISchemas::ObjectHistoryV1 to make it
+  # immutable
+  class ChangeLogEntry < Jamf::OAPISchemas::ObjectHistoryV1
 
-# include the modules loaded above
-class String
+    extend Jamf::Immutable
 
-  include JSSRubyExtensions::String::Predicates
-  include JSSRubyExtensions::String::Conversions
-  include JSSRubyExtensions::String::BackPorts
+  end # class ChangeLogEntry
 
-end
+end # module

data/lib/jamf/api/{attribute_classes → jamf_pro/other_classes}/ip_address.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -27,11 +27,6 @@
 module Jamf
 
   # handle nils and IPAddrs
-  # def new(an_ip, cnx: nil)
-  #   return nil if an_ip.nil?
-  #   an_ip = an_ip.to_s if an_ip.is_a? IPAddr
-  #   super an_ip, cnx: cnx
-  # end
 
   # A wrapper for IPAddr - allowing initialize to take an unused cnx:
   # and providing #to_jamf
@@ -42,8 +37,7 @@ module Jamf
     #
     # @param cnx [void] unused, but required
     #
-    def initialize(an_ip, cnx: nil)
-      cnx.to_s # shutup rubocop.
+    def initialize(an_ip)
 
       if an_ip.nil?
         @empty_ip = true

data/lib/jamf/api/jamf_pro/other_classes/pager.rb

@@ -0,0 +1,257 @@
+# Copyright 2022 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
+
+  # an object that performs a paged query for a pageable resource,
+  # possibly sorted and filtered. One of these is returned by class method
+  # .pager class method of CollectionResources the .change_log_pager method
+  # of ChangeLog resources
+  #
+  class Pager
+
+    # Constants
+    ########################################
+
+    MIN_PAGE_SIZE = 1
+
+    MAX_PAGE_SIZE = 2000
+
+    DEFAULT_PAGE_SIZE = 100
+
+    PAGE_SIZE_RANGE = (MIN_PAGE_SIZE..MAX_PAGE_SIZE).freeze
+
+    # Class Methods
+    ########################################
+
+    # Return all results from a pageable list path.
+    #
+    # Since the JPAPI always returns results in pages of 2000, if there are more
+    # than that many in the collection we must loop through the pages to get
+    # them all.
+    #
+    # @param list_path [String] The Resource URL path that provides the paged
+    #   query results
+    #
+    # @param sort [String ] The optional sort parameter for the query
+    #
+    # @param filter [String] The optional RSQL filter parameter for the query
+    #
+    # @param instantiate [Boolean] Defaults to false. Should the items in the
+    #   returned Array(s) be ruby instances of the CollectionObject subclass, or
+    #   plain Hashes of data as returned by the API?
+    #
+    # @param cnx [Jamf::Connection] The API connection to use, default: Jamf.cnx
+    #
+    # @return [Type] description_of_returned_object
+    #
+    def self.all_pages(list_path:, sort: nil, filter: nil, instantiate: false, cnx: Jamf.cnx)
+      sort &&= Jamf::Sortable.parse_url_sort_param(sort)
+      filter &&= Jamf::Filterable.parse_url_filter_param(filter)
+
+      pager = new(
+        page_size: MAX_PAGE_SIZE,
+        list_path: list_path,
+        sort: sort,
+        filter: filter,
+        instantiate: instantiate,
+        cnx: cnx
+      )
+
+      fetched_page = pager.fetch_next_page
+      data = fetched_page
+      until fetched_page.empty?
+        fetched_page = pager.fetch_next_page
+        data += fetched_page
+      end
+      data
+    end
+
+    # Attributes
+    ########################################
+
+    # @return [Jamf::Connection] The Connection object used for the query
+    attr_reader :cnx
+
+    # @return [String] The Resource URL path that provides the paged query results
+    attr_reader :list_path
+
+    # @return [String, nil] The optional sort parameter for the query,
+    attr_reader :sort
+
+    # @return [String, nil] The optional filter parameter for the query
+    attr_reader :filter
+
+    # @return [Integer] How many items to return per page
+    attr_reader :page_size
+
+    # @return [Integer] The page which will be returned when next_page is called
+    attr_reader :next_page
+
+    # @return [] The full r#source URL, with page_size, sort, and filter, but
+    #   without the 'page' parameter
+    attr_reader :query_path
+
+    # @return [Integer, nil] How many items are there in total? NOTE: this does
+    #   not apply any given filter, which might reduce the number of items
+    #   returned by a pager.
+    attr_reader :total_count
+
+    # @return [Integer, nil] How many pages needed to retrieve the total_count?
+    #  nil if using a filter, since that may return fewer than the total count.
+    attr_reader :total_pages
+
+    # Constructor
+    ########################################
+
+    # @param list_path [String] The Resource URL path that provides the paged
+    #   query results
+    #
+    # @param page_size [Integer] How many items to return per page
+    #
+    # @param sort [String ] The optional sort parameter for the query
+    #
+    # @param filter [String] The optional RSQL filter parameter for the query
+    #
+    # @param instantiate [Class] Should the results be instantiated as
+    #   the given class?
+    #
+    # @param cnx [Jamf::Connection]  The Connection object used for the query.
+    #   Defaults to the Default connection
+    #
+    ########################################
+    def initialize(list_path:, page_size: DEFAULT_PAGE_SIZE, sort: nil, filter: nil, instantiate: nil, cnx: Jamf.cnx)
+      validate_page_size(page_size)
+
+      @cnx = cnx
+      @list_path = list_path
+      @sort = Jamf::Sortable.parse_url_sort_param(sort)
+      @filter = Jamf::Filterable.parse_url_filter_param(filter)
+      @page_size = page_size
+      @instantiate = instantiate
+
+      # start with page 0, the first page
+      # This will be incremented and appended to the query path each time we call
+      # next_page
+      @next_page = 0
+
+      @query_path = "#{@list_path}?page-size=#{@page_size}#{@sort}#{@filter}"
+
+      # get one item which will contain the total count
+      @total_count = cnx.jp_get("#{@query_path}?page-size=1&page=0#{@filter}")[:totalCount]
+      # can't know total pages of filtered query
+      @total_pages = @filter ? nil : (@total_count / @page_size.to_f).ceil
+    end
+
+    # @return [Array] The next page of the collection, i.e. whichever page is
+    #   indicated in the next_page attribute.
+    ########################################
+    def fetch_next_page
+      page @next_page, increment_next: true
+    end
+
+    # Reset the pager to start at a specific page (by default, the beginning)
+    # so that #fetch_next_page will start from there the next time it's called.
+    def reset(to_page = 0)
+      to_page = 0 if to_page == :first
+      raise ArgumentError, 'Page number must be an Integer 0 or higher' if !to_page.is_a?(Integer) || to_page.negative?
+
+      @next_page = to_page
+    end
+
+    # Retrieve an arbitrary page of the result.
+    #
+    # IMPORTANT: In the Jamf Pro API, page numbers are zero-based! The first page
+    # is 0, the second is 1, and so on. Asking for page 27 will give you the
+    # 28th page of results
+    #
+    # If increment_next is true, then subsequent calls to #next_page will
+    # continue from whatever page number was requested.
+    #
+    # When increment_next is false (the default), the sequence of pages returned
+    # by #next_page is unchanged, regardless of which page you return here.
+    #
+    # @param number [Integer, Symbol] Which page to retrieve.
+    #   The Symbols :first and :last will work as expected. Otherwise, the
+    #   zero-based page number is needed. Will return an empty array if greater
+    #   than the total number of pages in the query result
+    #
+    # @param increment_next [Boolean] should the next_page value be reset to the
+    #   page number plus 1? This makes #fetch_next_page continue from this one.
+    #
+    # @return [Array] The desired page of the result, containing up to #page_size
+    #   items. Will be empty if the page is greater than the total available.
+    #
+    ########################################
+    def page(page_number, increment_next: false)
+      page_number = 0 if page_number == :first
+      if page_number == :last
+        raise Jamf::UnsupportedError, 'Cannot use :last with filtered queries' if @filter
+
+        page_number = (@total_pages - 1)
+      end
+
+      validate_page_number page_number
+
+      data = @cnx.jp_get "#{@query_path}&page=#{page_number}"
+      data =
+        if @instantiate
+          data[:results].map { |r| @instantiate.new r }
+        else
+          data[:results]
+        end
+
+      @next_page = (page_number + 1) if increment_next
+      data
+    end
+
+    # ensure valid page_size
+    #
+    # @param page_size [Integer] the page_size to be validated, must be in range
+    #
+    # @return [void]
+    #
+    def validate_page_size(page_size)
+      return if page_size.is_a?(Integer) && PAGE_SIZE_RANGE.cover?(page_size)
+
+      raise ArgumentError, "page_size must be an Integer from #{MIN_PAGE_SIZE} to #{MAX_PAGE_SIZE}"
+    end
+    private :validate_page_size
+
+    # ensure valid page_number
+    #
+    # @param page [Integer] the page number requested, must be >= 0
+    #
+    # @return [void]
+    #
+    def validate_page_number(page_number)
+      return if page_number.is_a?(Integer) && page_number >= 0
+
+      raise ArgumentError, 'Page number must be an Integer 0 or higher'
+    end
+    private :validate_page_number
+
+  end # class Pager
+
+end # Jamf

data/lib/jamf/api/{attribute_classes → jamf_pro/other_classes}/timestamp.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -25,16 +25,22 @@
 
 module Jamf
 
-  # A timestamp as used in the JAMF API JSON data
+  # A timestamp as used in the Jamf Pro API JSON data
   #
-  # Instantiate with a String in iso6801 format (used in the API JSON for
-  # all(?) time/date values), or with a Time or Jamf::Timestamp instance, or with
-  # an Integer unix epoch, which is treated Jamf-style if 1_000_000_000_000 or
-  # higher
+  # Instantiate with any of:
+  #   - A string parsable by Time.parse. Timestamps from the API are always
+  #     strings in iso6801 format
+  #   - a Time or Jamf::Timestamp instance
+  #   - an Integer, or Stringified Integer, a unix epoch value. If it is
+  #     1_000_000_000_000 or higher, it is treated as a Jamf-stype epoch,
+  #     meaning the last 3 digits are milliseconds.
+  #   - nil or an empty string, which will 'unset' a time value with an empty
+  #     string when sent back to the API
   #
-  # To unset a timestamp value, instantiate with nil or an empty string. The
-  # Time value will be '1970-01-01 00:00:00 -0000', the unix epoch,
-  # and the to_jamf method will return an empty string.
+  # To unset a timestamp value in the API, instantiate one of these with
+  # nil or an empty string. The Time value will be '1970-01-01 00:00:00 -0000',
+  # the unix epoch, and the to_jamf method will return an empty string, which
+  # is what will be sent to the API
   #
   # NOTE: Passing '1970-01-01 00:00:00 -0000' or the equivalent explicitly
   # will NOT be treated as an empty timestamp, but as that actual value.
@@ -48,7 +54,7 @@ module Jamf
   # - use .to_f for a unix epoch with fractions
   #
   # Use #to_jamf to get the formated string to use in JSON for sending to the
-  # API - it *should* always be in ISO8601 format
+  # API - it *should* always be in ISO8601 format, or an empty string.
   #
   class Timestamp < ::Time
 
@@ -70,9 +76,7 @@ module Jamf
 
     # @param tstamp[String,Integer,Time] A representation of a timestampe
     #
-    # @param _args [void] unused, but required for JSONObject init.
-    #
-    def initialize(tstamp, **_args)
+    def initialize(tstamp)
       # use a Time object to parse the input and generate our own
       # object
       time = parse_init_tstamp(tstamp)
@@ -83,7 +87,7 @@ module Jamf
         time.day,
         time.hour,
         time.min,
-        (time.sec + (time.usec/1_000_000.0)).round(3),
+        (time.sec + (time.usec / 1_000_000.0)).round(3),
         time.utc_offset
       )
     end

data/lib/jamf/{api/mixins/base_class.rb → base_class.rb}

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in
@@ -54,16 +54,16 @@ module Jamf
       Jamf::BaseClass.base_classes.include? self
     end
 
-    # Can't allocate if base class
-    def allocate(*args, &block)
-      stop_if_base_class ALLOCATION_ACTION
-      super
-    end
+    # # Can't allocate if base class
+    # def allocate(*args, **kwargs, &block)
+    #   stop_if_base_class ALLOCATION_ACTION
+    #   super
+    # end
 
     # Can't instantiate if base_class
-    def new(*args, &block)
+    def new(*args, **kwargs, &block)
       stop_if_base_class INSTANTIATION_ACTION
-      super
+      super(*args, **kwargs, &block)
     end
 
     # raise an exception if this class is a base class