ruby-jss 1.6.0 → 2.0.0a11

data/lib/{jss/api_object → jamf/api/classic/api_objects}/self_servable.rb

@@ -1,5 +1,5 @@
 
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,10 +24,8 @@
 ###
 ###
 
-require 'jss/api_object/self_servable/icon'
-
 ###
-module JSS
+module Jamf
 
   # Module Variables
   #####################################
@@ -51,12 +49,12 @@ module JSS
   # - :security
   #
   # Additionally, items that apper in macOS Slf Svc have these keys:
-  # - :self_service_display_name (but not JSS::MacApplication)
+  # - :self_service_display_name (but not Jamf::MacApplication)
   # - :install_button_text
-  # - :reinstall_button_text (but not JSS::MacApplication)
+  # - :reinstall_button_text (but not Jamf::MacApplication)
   # - :force_users_to_view_description
   # - :notification
-  # - :notification_location # PENDING API FIX, and also, not JSS::MacApplication
+  # - :notification_location # PENDING API FIX, and also, not Jamf::MacApplication
   # - :notification_subject
   # - :notification_message
   #
@@ -70,7 +68,7 @@ module JSS
   # Classes including this module *MUST*:
   # - call {#add_self_service_xml(xmldoc)} in their #rest_xml method
   #
-  # IMPORTANT: Since SelfServable also includes #{JSS::Uploadable}, for uploading icons,
+  # IMPORTANT: Since SelfServable also includes #{Jamf::Uploadable}, for uploading icons,
   # see that module for its requirements.
   #
   #
@@ -113,6 +111,10 @@ module JSS
     # Self Service data is dealt with in the API data of the different
     # self-servable classes.
     #
+    # NOTE: The keys are the string versions of the Classes themselves, so that
+    # we don't cause circular dependencies when loading these classes with
+    # zeitwerk
+    #
     #  - in_self_service_data_path: Array, In the API data hash (the @init_data)
     #      where to find the value indicicating that a thing is in self service.
     #      e.g. [:self_service, :use_for_self_service] means
@@ -154,7 +156,7 @@ module JSS
     # self service ruby code in this one module.
     #
     SELF_SERVICE_CLASSES = {
-      JSS::Policy => {
+      'Jamf::Policy' => {
         in_self_service_data_path: %i[self_service use_for_self_service],
         in_self_service: true,
         not_in_self_service: false,
@@ -165,7 +167,7 @@ module JSS
         notifications_supported: :ssvc_only,
         url_entity: 'policy'
       },
-      JSS::PatchPolicy => {
+      'Jamf::PatchPolicy' => {
         in_self_service_data_path: %i[general distribution_method],
         in_self_service: PATCHPOL_SELF_SERVICE,
         not_in_self_service: PATCHPOL_AUTO,
@@ -177,7 +179,7 @@ module JSS
         notifications_supported: :ssvc_and_nctr,
         notification_reminders: true
       },
-      JSS::MacApplication => {
+      'Jamf::MacApplication' => {
         in_self_service_data_path: %i[general deployment_type],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL_OR_PROMPT,
@@ -189,7 +191,7 @@ module JSS
         url_entity: 'app'
         # OTHER BUG: no notification options seem to be changable via the API
       },
-      JSS::OSXConfigurationProfile => {
+      'Jamf::OSXConfigurationProfile' => {
         in_self_service_data_path: %i[general distribution_method],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL,
@@ -200,7 +202,7 @@ module JSS
         notifications_supported: :ssvc_only,
         url_entity: 'configprofile'
       },
-      JSS::EBook => {
+      'Jamf::Ebook' => {
         in_self_service_data_path: %i[general deployment_type],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL_OR_PROMPT,
@@ -211,7 +213,7 @@ module JSS
         notifications_supported: :ssvc_only,
         url_entity: 'ebook'
       },
-      JSS::MobileDeviceApplication => {
+      'Jamf::MobileDeviceApplication' => {
         in_self_service_data_path: %i[general deployment_type],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL_OR_PROMPT,
@@ -220,7 +222,7 @@ module JSS
         can_display_in_categories: true,
         can_feature_in_categories: false
       },
-      JSS::MobileDeviceConfigurationProfile => {
+      'Jamf::MobileDeviceConfigurationProfile' => {
         in_self_service_data_path: %i[general deployment_method],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL,
@@ -241,7 +243,7 @@ module JSS
     attr_reader :in_self_service
     alias in_self_service? in_self_service
 
-    # @return [JSS::Icon, nil] The icon used in self-service
+    # @return [Jamf::Icon, nil] The icon used in self-service
     attr_reader :icon
     alias self_service_icon icon
 
@@ -361,9 +363,9 @@ module JSS
     #
     def self_service_display_name=(new_val)
       new_val = new_val.strip
-      return nil if @self_service_dislay_name == new_val
-      raise JSS::InvalidDataError, 'Only macOS Self Service items have display names' unless self_service_targets.include? :macos
-      @self_service_dislay_name = new_val
+      return nil if @self_service_display_name == new_val
+      raise Jamf::InvalidDataError, 'Only macOS Self Service items have display names' unless self_service_targets.include? :macos
+      @self_service_display_name = new_val
       @need_to_update = true
     end
     # alias for backward compatibility with the typo
@@ -376,7 +378,7 @@ module JSS
     def self_service_install_button_text=(new_val)
       new_val = new_val.strip
       return nil if @self_service_install_button_text == new_val
-      raise JSS::InvalidDataError, 'Only macOS Self Service Items can have custom button text' unless self_service_targets.include? :macos
+      raise Jamf::InvalidDataError, 'Only macOS Self Service Items can have custom button text' unless self_service_targets.include? :macos
       @self_service_install_button_text = new_val
       @need_to_update = true
     end
@@ -388,7 +390,7 @@ module JSS
     def self_service_reinstall_button_text=(new_val)
       new_val = new_val.strip
       return nil if @self_service_reinstall_button_text == new_val
-      raise JSS::InvalidDataError, 'Only macOS Self Service Items can have custom button text' unless self_service_targets.include? :macos
+      raise Jamf::InvalidDataError, 'Only macOS Self Service Items can have custom button text' unless self_service_targets.include? :macos
       @self_service_reinstall_button_text = new_val
       @need_to_update = true
     end
@@ -400,7 +402,7 @@ module JSS
     def self_service_feature_on_main_page=(new_val)
       return nil if @self_service_feature_on_main_page == new_val
       return nil unless @self_service_data_config[:can_feature_in_categories]
-      raise JSS::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+      raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
       @self_service_feature_on_main_page = new_val
       @need_to_update = true
     end
@@ -412,8 +414,8 @@ module JSS
     #
     def self_service_force_users_to_view_description=(new_val)
       return nil if @self_service_force_users_to_view_description == new_val
-      raise JSS::InvalidDataError, 'Only macOS Self Service Items can force users to view description' unless self_service_targets.include? :macos
-      raise JSS::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
+      raise Jamf::InvalidDataError, 'Only macOS Self Service Items can force users to view description' unless self_service_targets.include? :macos
+      raise Jamf::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
       @self_service_force_users_to_view_description = new_val
       @need_to_update = true
     end
@@ -433,13 +435,13 @@ module JSS
     # @return [void]
     #
     def add_self_service_category(new_cat, display_in: true, feature_in: false)
-      new_cat = JSS::Category.map_all_ids_to(:name, api: @api)[new_cat] if new_cat.is_a? Integer
+      new_cat = Jamf::Category.map_all_ids_to(:name, cnx: @cnx)[new_cat] if new_cat.is_a? Integer
       feature_in = false if display_in == false
-      raise JSS::NoSuchItemError, "No category '#{new_cat}' in the JSS" unless JSS::Category.all_names(:refresh, api: @api).include? new_cat
+      raise Jamf::NoSuchItemError, "No category '#{new_cat}' in the JSS" unless Jamf::Category.all_names(:refresh, cnx: @cnx).include? new_cat
 
-      raise JSS::InvalidDataError, 'display_in must be true or false' unless display_in.jss_boolean?
+      raise Jamf::InvalidDataError, 'display_in must be true or false' unless display_in.jss_boolean?
 
-      raise JSS::InvalidDataError, 'feature_in must be true or false' unless feature_in.jss_boolean?
+      raise Jamf::InvalidDataError, 'feature_in must be true or false' unless feature_in.jss_boolean?
 
       new_data = { name: new_cat }
       new_data[:display_in] = display_in if @self_service_data_config[:can_display_in_categories]
@@ -502,7 +504,7 @@ module JSS
     def self_service_notifications_enabled=(new_val)
       return if new_val == self_service_notifications_enabled
       validate_notifications_supported
-      JSS::Validate.boolean new_val
+      Jamf::Validate.boolean new_val
       @self_service_notifications_enabled = new_val
       @need_to_update = true
     end
@@ -523,7 +525,7 @@ module JSS
         raise "JAMF BUG: Until Jamf fixes API bugs in #{self.class}, you can only set Self Service notifications to :ssvc_only. Use the WebUI to activate Notification Center notifications"
       end
 
-      raise JSS::InvalidDataError, "type must be one of: :#{NOTIFICATION_TYPES.keys.join ', :'}" unless NOTIFICATION_TYPES.key? type
+      raise Jamf::InvalidDataError, "type must be one of: :#{NOTIFICATION_TYPES.keys.join ', :'}" unless NOTIFICATION_TYPES.key? type
 
       @self_service_notification_type = type
       @need_to_update = true
@@ -562,7 +564,7 @@ module JSS
     def self_service_reminders_enabled=(new_val)
       return if new_val == self_service_reminders_enabled
       validate_notification_reminders_supported
-      JSS::Validate.boolean new_val
+      Jamf::Validate.boolean new_val
       @self_service_reminders_enabled = new_val
       @need_to_update = true
     end
@@ -576,14 +578,14 @@ module JSS
     def self_service_reminder_frequency=(days)
       return if days == self_service_reminder_frequency
       validate_notification_reminders_supported
-      JSS::Validate.integer days
+      Jamf::Validate.integer days
       @self_service_reminder_frequency = days
       @need_to_update = true
     end
 
     # Set a new Self Service icon for this object.
     #
-    # Since JSS::Icon objects are read-only,
+    # Since Jamf::Icon objects are read-only,
     # the icon can only be changed by supplying the id number
     # of an icon already existing in the JSS, or a path to
     # a local file, which will be uploaded to the JSS and added
@@ -603,7 +605,7 @@ module JSS
         @need_to_update = true
       else
         unless uploadable? && defined?(self.class::UPLOAD_TYPES) && self.class::UPLOAD_TYPES.key?(:icon)
-          raise JSS::UnsupportedError, "Class #{self.class} does not support icon uploads."
+          raise Jamf::UnsupportedError, "Class #{self.class} does not support icon uploads."
         end
         new_icon = Pathname.new new_icon
         upload(:icon, new_icon)
@@ -692,7 +694,7 @@ module JSS
   </self_service>
 </#{self.class::RSRC_OBJECT_KEY}>
       ENDXML
-      @api.put_rsrc rest_rsrc, xml
+      @cnx.c_put rest_rsrc, xml
       @need_ss_notification_activation_hack = nil
     end
 
@@ -704,7 +706,7 @@ module JSS
     # @return [void]
     #
     def parse_self_service
-      @self_service_data_config = SELF_SERVICE_CLASSES[self.class]
+      @self_service_data_config = SELF_SERVICE_CLASSES[self.class.to_s]
 
       subset_key = @self_service_data_config[:self_service_subset] ? @self_service_data_config[:self_service_subset] : :self_service
 
@@ -715,7 +717,7 @@ module JSS
 
       @self_service_description = ss_data[:self_service_description]
 
-      @icon = JSS::Icon.new(ss_data[:self_service_icon]) if ss_data[:self_service_icon]
+      @icon = Jamf::Icon.new(ss_data[:self_service_icon]) if ss_data[:self_service_icon]
 
       @self_service_feature_on_main_page = ss_data[:feature_on_main_page]
 
@@ -767,7 +769,7 @@ module JSS
       # oldstyle/broken, we need the XML to know if notifications are turned on
       if @self_service_data_config[:notifications_supported] == :ssvc_only && @in_jss
         ssrsrc = "#{rest_rsrc}/subset/selfservice"
-        raw_xml = api.get_rsrc(ssrsrc, :xml)
+        raw_xml = cnx.c_get(ssrsrc, :xml)
         @self_service_notifications_enabled = raw_xml.include? '<notification>true</notification>'
         @self_service_notification_type = NOTIFICATION_TYPES.invert[ss_data[:notification]]
         @self_service_notification_subject = ss_data[:notification_subject]
@@ -798,13 +800,13 @@ module JSS
     #
     def refresh_icon
       return nil unless @in_jss
-      fresh_data = @api.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY]
+      fresh_data = @cnx.c_get(@rest_rsrc)[self.class::RSRC_OBJECT_KEY]
       subset_key = @self_service_data_config[:self_service_subset] ? @self_service_data_config[:self_service_subset] : :self_service
 
       ss_data = fresh_data[subset_key]
 
       icon_data = ss_data[:self_service_icon]
-      @icon = JSS::Icon.new icon_data
+      @icon = Jamf::Icon.new icon_data
     end # refresh icon
 
     # Add approriate XML for self service data to the XML document for this
@@ -890,7 +892,7 @@ module JSS
       ssvc.add_element('install_button_text').text = self_service_install_button_text if self_service_install_button_text
       ssvc.add_element('force_users_to_view_description').text = self_service_force_users_to_view_description.to_s
 
-      return if self.class == JSS::MacApplication
+      return if self.class == Jamf::MacApplication
 
       ssvc.add_element('self_service_display_name').text = self_service_display_name if self_service_display_name
       ssvc.add_element('reinstall_button_text').text = self_service_reinstall_button_text if self_service_reinstall_button_text
@@ -926,29 +928,29 @@ module JSS
 
     # Raise an error if user_removable settings are wrong
     def validate_user_removable(new_val)
-      raise JSS::UnsupportedError, 'User removal settings not applicable to this class' unless self_service_payload == :profile
+      raise Jamf::UnsupportedError, 'User removal settings not applicable to this class' unless self_service_payload == :profile
 
-      raise JSS::UnsupportedError, 'Removal :with_auth not applicable to this class' if new_val == :with_auth && !self_service_targets.include?(:ios)
+      raise Jamf::UnsupportedError, 'Removal :with_auth not applicable to this class' if new_val == :with_auth && !self_service_targets.include?(:ios)
 
-      raise JSS::InvalidDataError, "Value must be one of: :#{PROFILE_REMOVAL_BY_USER.keys.join(', :')}" unless PROFILE_REMOVAL_BY_USER.key?(new_val)
+      raise Jamf::InvalidDataError, "Value must be one of: :#{PROFILE_REMOVAL_BY_USER.keys.join(', :')}" unless PROFILE_REMOVAL_BY_USER.key?(new_val)
     end
 
     # Raise an error if an icon id is not valid
     def validate_icon(id)
-      return nil unless JSS::DB_CNX.connected?
-      raise JSS::NoSuchItemError, "No icon with id #{id}" unless JSS::Icon.all_ids.include? id
+      return nil unless Jamf::DB_CNX.connected?
+      raise Jamf::NoSuchItemError, "No icon with id #{id}" unless Jamf::Icon.all_ids.include? id
     end
 
     # Raise an error if notifications aren't supported
     def validate_notifications_supported
-      raise JSS::UnsupportedError, "#{self.class} doesn't support Self Service notifications" unless @self_service_data_config[:notifications_supported]
+      raise Jamf::UnsupportedError, "#{self.class} doesn't support Self Service notifications" unless @self_service_data_config[:notifications_supported]
     end
 
     # Raise an error if notification reminders aren't supported
     def validate_notification_reminders_supported
-      raise JSS::UnsupportedError, "#{self.class} doesn't support Self Service notifications" unless @self_service_data_config[:notification_reminders]
+      raise Jamf::UnsupportedError, "#{self.class} doesn't support Self Service notifications" unless @self_service_data_config[:notification_reminders]
     end
 
   end # module SelfServable
 
-end # module JSS
+end # module Jamf

data/lib/{jss/api_object → jamf/api/classic/api_objects}/sitable.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 ###
 
 ###
-module JSS
+module Jamf
 
   # Module Variables
   #####################################
@@ -92,13 +92,13 @@ module JSS
       @site_id || NO_SITE_ID
     end # cat id
 
-    # The JSS::Site instance for this object's site
+    # The Jamf::Site instance for this object's site
     #
-    # @return [JSS::Site] The JSS::Site instance for this object's site
+    # @return [Jamf::Site] The Jamf::Site instance for this object's site
     #
     def site_object
       return nil unless site_assigned?
-      JSS::Site.fetch id: @site_id
+      Jamf::Site.fetch id: @site_id
     end # cat obj
 
     # Does this object have a site assigned?
@@ -130,12 +130,12 @@ module JSS
         return
       end
 
-      new_id = JSS::Site.valid_id new_site, api: @api
-      new_name = JSS::Site.map_all_ids_to(:name, api: @api)[new_id]
+      new_id = Jamf::Site.valid_id new_site, cnx: @cnx
+      new_name = Jamf::Site.map_all_ids_to(:name, cnx: @cnx)[new_id]
       # no change, go home.
       return nil if new_name == @site_name
 
-      raise JSS::NoSuchItemError, "Site '#{new_site}' is not known to the JSS" unless new_id
+      raise Jamf::NoSuchItemError, "Site '#{new_site}' is not known to the JSS" unless new_id
 
       @site_name = new_name
       @site_id = new_id

data/lib/{jss/api_object → jamf/api/classic/api_objects}/site.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# Copyright 2022 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 #
 
 #
-module JSS
+module Jamf
 
   # Classes
   ###################################
@@ -33,14 +33,14 @@ module JSS
   #
   # These are simple, in that they only have an ID and a name.
   #
-  # @see JSS::APIObject
+  # @see Jamf::APIObject
   #
-  class Site < JSS::APIObject
+  class Site < Jamf::APIObject
 
     # Mix-Ins
     ###################################
-    include JSS::Creatable
-    include JSS::Updatable
+    include Jamf::Creatable
+    include Jamf::Updatable
 
     # Class Constants
     ###################################

data/lib/{jss/api_object → jamf/api/classic/api_objects}/software_update_server.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 ###
 
 ###
-module JSS
+module Jamf
 
   #####################################
   ### Module Variables
@@ -43,9 +43,9 @@ module JSS
   ###
   ### Only minimally implemented, for access to the APIObject list methods
   ###
-  ### @see JSS::APIObject
+  ### @see Jamf::APIObject
   ###
-  class SoftwareUpdateServer < JSS::APIObject
+  class SoftwareUpdateServer < Jamf::APIObject
 
     #####################################
     ### Mix-Ins
@@ -95,7 +95,7 @@ module JSS
     ###
     ### @see SS::APIObject#initialize
     ###
-    def initialize (args = {})
+    def initialize(**args)
       super
       @ip_address = @init_data[:ip_address]
       @port = @init_data[:port]

data/lib/{jss/api_object → jamf/api/classic/api_objects}/updatable.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 ###
 
 ### A mix-in module providing object-updating via the JSS API.
-module JSS
+module Jamf
 
   # Module Variables
   #####################################
@@ -37,7 +37,7 @@ module JSS
 
   # A mix-in module that allows objects to be updated in the JSS via the API.
   #
-  # When a JSS::APIObject subclass includes this module, instances of that
+  # When a Jamf::APIObject subclass includes this module, instances of that
   # subclass can be modified in the JSS using the {#update} or {APIObject#save} methods.
   #
   # Such classes should define setter methods for any values that they wish to
@@ -76,10 +76,10 @@ module JSS
     #
     def name=(newname)
       return nil if @name == newname
-      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
-      raise JSS::InvalidDataError, "Names can't be empty!" if newname.to_s.empty?
-      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} named '#{newname}' already exsists in the JSS" \
-        if self.class.all_names(:refresh, api: @api).include? newname
+      raise Jamf::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
+      raise Jamf::InvalidDataError, "Names can't be empty!" if newname.to_s.empty?
+      raise Jamf::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} named '#{newname}' already exsists in the JSS" \
+        if self.class.all_names(:refresh, cnx: @cnx).include? newname
       @name = newname
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape @name.to_s}" if @rest_rsrc.include? '/name/'
       @need_to_update = true
@@ -87,23 +87,23 @@ module JSS
 
     # Save changes to the JSS
     #
-    # @return [Boolean] success
+    # @return [Integer] The object id
     #
-    def update
+    def update_in_jamf
       return nil unless @need_to_update
-      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
-      raise JSS::NoSuchItemError, "Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY} in the JSS before updating it." unless @in_jss
+      raise Jamf::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
 
-      @api.put_rsrc @rest_rsrc, rest_xml
+      @cnx.c_put @rest_rsrc, rest_xml
       @need_to_update = false
       refresh_icon if self_servable?
 
       # clear any cached all-lists or id-maps for this class
       # so they'll re-cache as needed
-      @api.flushcache self.class::RSRC_LIST_KEY
+      @cnx.flushcache self.class::RSRC_LIST_KEY
 
       @id
     end # update
+    private :update_in_jamf
 
   end # module Creatable
 

data/lib/{jss/api_object → jamf/api/classic/api_objects}/uploadable.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 ###
 
 ###
-module JSS
+module Jamf
 
   #####################################
   # Module Variables
@@ -46,8 +46,8 @@ module JSS
   #
   #  UPLOAD_TYPES = {
   #     :icon => :mobiledeviceapplicationsicon
-  #     :app => mobiledeviceapplicationsipa
-  #     :attachment => mobiledeviceapplications
+  #     :app => :mobiledeviceapplicationsipa
+  #     :attachment => :mobiledeviceapplications
   #   }
   #
   # with one pair for each type of upload that the class can handle.
@@ -87,7 +87,6 @@ module JSS
   #
   module Uploadable
 
-    #####################################
     #  Constants
     #####################################
 
@@ -95,17 +94,68 @@ module JSS
 
     UPLOAD_RSRC_PREFIX = 'fileuploads'.freeze
 
-    #####################################
-    #  Variables
-    #####################################
+    FORCE_IPA_UPLOAD_PARAM = 'FORCE_IPA_UPLOAD'.freeze
 
+    #  Class/Module Methods
     #####################################
-    #  Methods
+    module ClassMethods
+
+      # Upload a file to the JSS to be stored with an item of the
+      # class mixing in the Uploadable module.
+      #
+      # This class method does not require fetching a Ruby instance first,
+      # but the matching instance method will work for a specific instance if
+      # it's already been fetched.
+      #
+      # @param ident[Integer, String] A unique identifier for the object taking the upload
+      #
+      # @param type[Symbol] the type of upload happening.
+      #   Must be one of the keys defined in the class's UPLOAD_TYPES Hash.
+      #
+      # @param local_file[String, Pathname] String or Pathname pointing to the
+      #   locally-readable file to be uploaded.
+      #
+      # @param force_ipa_upload[Boolean] Should the server upload the .ipa file to
+      #   JCDS or AWS if such are confgured for use?
+      #
+      # @param cnx [Jamf::Connection] the connection object for the operation.
+      #   defaults to the default connection for the JSS module.
+      #
+      # @return [Boolean] was the  upload successful?
+      #
+      def upload(ident, type, local_file, force_ipa_upload: false, api: nil, cnx: Jamf.cnx)
+        cnx = api if api
+
+        id = valid_id ident, :refresh, cnx: cnx
+        raise "No #{self::RSRC_OBJECT_KEY} matching '#{ident}'" unless id
+
+        # the type has to be defined in the class including this module.
+        raise Jamf::InvalidDataError, "#{self::RSRC_LIST_KEY} only take uploads of type: :#{self::UPLOAD_TYPES.keys.join(', :')}." \
+          unless self::UPLOAD_TYPES.key? type
+
+        # figure out the resource after the UPLOAD_RSRC_PREFIX
+        upload_rsrc = "#{UPLOAD_RSRC_PREFIX}/#{self::UPLOAD_TYPES[type]}/id/#{id}"
+
+        upload_rsrc << "?#{FORCE_IPA_UPLOAD_PARAM}=true" if self::UPLOAD_TYPES[type] == :mobiledeviceapplicationsipa && force_ipa_upload
+
+        cnx.upload upload_rsrc, local_file
+      end # def upload
+
+    end # module classmethods
+
+    # this loads the class methods (via 'extend') when the instanace methods
+    # are included
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    #  Instance Methods
     #####################################
 
-
-    # Upload a file to the JSS via the REST Resource of the
-    # object to which this module is mixed in.
+    # instance method wrapper for class method
+    #
+    # Upload a file to the JSS to be stored with this instance of the
+    # class mixing in the Uploadable module
     #
     # @param type[Symbol] the type of upload happening.
     #   Must be one of the keys defined in the class's UPLOAD_TYPES Hash.
@@ -113,26 +163,18 @@ module JSS
     # @param local_file[String, Pathname] String or Pathname pointing to the
     #   locally-readable file to be uploaded.
     #
-    # @return [String] The xml response from the server.
+    # @param force_ipa_upload[Boolean] Should the server upload the .ipa file to
+    #   JCDS or AWS if such are confgured for use?
     #
-    def upload(type, local_file)
+    # @return [Boolean] was the  upload successful?
+    #
+    def upload(type, local_file, force_ipa_upload: false)
       # the thing's gotta be in the JSS, and have an @id
-      raise JSS::NoSuchItemError, 'Create this #{self.class::RSRC_OBJECT_KEY} in the JSS before uploading files to it.' unless @id && @in_jss
-
-      # the type has to be defined in the class of self.
-      raise JSS::InvalidDataError, "#{self.class::RSRC_LIST_KEY} only take uploads of type: :#{self.class::UPLOAD_TYPES.keys.join(', :')}." \
-        unless self.class::UPLOAD_TYPES.keys.include? type
-
-      # figure out the resource after the UPLOAD_RSRC_PREFIX
-      upload_rsrc = "#{UPLOAD_RSRC_PREFIX}/#{self.class::UPLOAD_TYPES[type]}/id/#{@id}"
-
-      # make a File object to hand to REST. 'rb' = read,binary
-      file = File.new local_file.to_s, 'rb'
+      raise Jamf::NoSuchItemError, "Create this #{self.class::RSRC_OBJECT_KEY} in the JSS before uploading files to it." unless @id && @in_jss
 
-      # upload it!
-      @api.cnx[upload_rsrc].post name: file
-    end # def upload file
+      self.class.upload @id, type, local_file, force_ipa_upload: force_ipa_upload, cnx: @cnx
+    end
 
   end # module FileUpload
 
-end # module JSS
+end # module Jamf