windoo 1.0.1

data/lib/windoo/mixins/software_title/extension_attribute.rb

@@ -0,0 +1,106 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  module Mixins
+
+    module SoftwareTitle
+
+      # An module that manages the ExtensionAttribute in a
+      # SoftwareTitle.
+      #
+      # Even though 'extensionAttributes' is plural, and
+      # they come from the server in an Array, at the moment there
+      # can only be one per SoftwareTitle.
+      #
+      # This module hides that confusion and allows you to work with
+      # just one
+      #
+      # If there's already an extension attribute, you can access it
+      # from the #extensionAttribute getter, and use that to directly
+      # update its values.
+      #
+      module ExtensionAttribute
+
+        # Construcor
+        ######################
+        def initialize(**init_data)
+          super
+          @extensionAttribute =
+            if @init_data[:extensionAttributes]&.first
+              Windoo::ExtensionAttribute.instantiate_from_container(
+                container: self,
+                **@init_data[:extensionAttributes].first
+              )
+            end
+        end
+
+        # Public Instance Methods
+        ####################################
+
+        # Add an ExtensionAttribute to this SoftwareTitle.
+        #
+        # NOTE: There can be only one EA per SoftwareTitle. You will
+        # get an error if one already exists.
+        #
+        # @param key [String] The name of the extension attribute as
+        #   it appears in Jamf Pro
+        #   NOTE: must be unique in the Title Editor AND Jamf Pro.
+        #
+        # @param displayName [String] The name of the extension
+        #   attribute as it appears in Title Editor
+        #
+        # @param script [String] The script of that returns
+        #   the value of the Extension Attribute on a computer.
+        #   It must be a String that starts with '#!'
+        #
+        # @return [Integer] The id of the new Extension Attribute
+        #
+        def add_extensionAttribute(key:, displayName:, script:)
+          if @extensionAttribute
+            raise Windoo::AlreadyExistsError,
+                  'This SoftwareTitle already has an Extension Attribute. Either delete it before creating a new one, or update the existing one.'
+          end
+
+          @extensionAttribute = Windoo::ExtensionAttribute.create(
+            container: self,
+            key: key,
+            displayName: displayName,
+            script: script
+          )
+
+          @extensionAttribute.extensionAttributeId
+        end
+
+        # Delete the ExtensionAttribute from this SoftwareTitle
+        #
+        # When deleting an EA via this method, it is deleted
+        # from the server immediately, there is no need to #save
+        # the SoftwareTitle
+        #
+        # @return [Integer] The id of the deleted Extension Attribute
+        #
+        def delete_extensionAttribute
+          return unless @extensionAttribute
+
+          deleted_id = @extensionAttribute.delete
+          @extensionAttribute = nil
+
+          deleted_id
+        rescue Windoo::NoSuchItemError
+          nil
+        end
+
+      end # module ExtensionAttribute
+
+    end # module SoftwareTitle
+
+  end # module Mixins
+
+end # module Windoo

data/lib/windoo/mixins/utility.rb

@@ -0,0 +1,23 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module Windoo
+
+  module Mixins
+
+    # This should be extended into the Windoo module
+    module Utility
+
+      def self.extended(extender)
+        Windoo.verbose_extend extender, self
+      end
+
+    end # Utility
+
+  end #  module Mixins
+
+end # Windoo

data/lib/windoo/objects/capability.rb

@@ -0,0 +1,82 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # The class for dealing with the capabilities of Patches in the
+  # Title Editor
+  #
+  # A capability is one criterion, a group of which define which computers
+  # are capable of running, and this allowed to install, a Patch.
+  class Capability < Windoo::BaseClasses::Criterion
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'capabilities'
+
+    CONTAINER_CLASS = Windoo::Patch
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute capabilityId
+      # @return [Integer] The id number of this capability
+      capabilityId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute patchId
+      # @return [Integer] The id number of the Patch which uses this capability
+      patchId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      }
+
+    }.freeze
+
+    # Public Class Methods
+    ######################
+
+    ####
+    def self.fetch(*_args)
+      raise Windoo::UnsupportedError, 'Capabilities are fetched as part of the Patch that contains them'
+    end
+
+    # Private Instance Methods
+    ##########################################
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @capabilityId = post_response[:capabilityId]
+      @patchId = post_response[:patchId]
+      @capabilityId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(_put_response)
+      @capabilityId
+    end
+
+  end # class Capability
+
+end # Module Windoo

data/lib/windoo/objects/capability_manager.rb

@@ -0,0 +1,52 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # A {Windoo::BaseClasses::CriteriaManager CriteriaManager} for dealing with the
+  # {Windoo::Capability Capabilities} of a {Windoo::Patch Patch}
+  #
+  # An instance of this is returned by {Patch#capabilities}
+  #
+  class CapabilityManager < Windoo::BaseClasses::CriteriaManager
+
+    # Constants
+    ######################
+
+    MEMBER_CLASS = Windoo::Capability
+
+    # Public Instance Methods
+    #################################
+
+    # Override this method to disable the containing patch
+    # if there are no more capabilities.
+    #
+    def delete_criterion(id)
+      deleted_id = super
+
+      # patches without a capabliity are not valid
+      # so must be disabled
+      @container.disable if @managed_array.empty?
+
+      deleted_id
+    end
+
+    # Delete all the criteria
+    #
+    # @return [void]
+    #
+    def delete_all_criteria
+      super
+      # patches without a capabliity are not valid
+      # so must be disabled
+      @container.disable
+    end
+
+  end # class RequirementManager
+
+end # Module Windoo

data/lib/windoo/objects/component.rb

@@ -0,0 +1,99 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # A component holds a bunch of criteria defining which computers
+  # have a specific patch version installed.
+  class Component < Windoo::BaseClasses::JSONObject
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'components'
+
+    CONTAINER_CLASS = Windoo::Patch
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute componentId
+      # @return [Integer] The id number of this component
+      componentId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute patchId
+      # @return [Integer] The id number of the patch which uses this component
+      patchId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute name
+      # @return [String] The name of the Software Title for this patch
+      name: {
+        class: :String
+      },
+
+      # @!attribute version
+      # @return [String] The version installed by this patch
+      version: {
+        class: :String
+      },
+
+      # @!attribute criteria
+      # @return [Array<Windoo::ComponentCriterion>] The criteria used by
+      # this component.
+      criteria: {
+        class: Windoo::ComponentCriteriaManager,
+        do_not_send: true
+      }
+
+    }.freeze
+
+    # Constructor
+    ######################
+
+    def initialize(**init_data)
+      super
+      @criteria ||= []
+      @criteria = Windoo::ComponentCriteriaManager.new @criteria, container: self
+    end
+
+    # Private Instance Methods
+    ##########################################
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @componentId = post_response[:componentId]
+      @patchId = post_response[:patchId]
+      @componentId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(_put_response)
+      @componentId
+    end
+
+  end # class Component
+
+end # Module Windoo

data/lib/windoo/objects/component_criteria_manager.rb

@@ -0,0 +1,26 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # A {Windoo::BaseClasses::CriteriaManager CriteriaManager} for dealing with the
+  # {Windoo::CompnentCriterion CompnentCriteria} of a {Windoo::Component Component}
+  # of a {Windoo::Patch Patch}
+  #
+  # An instance of this is returned by {Component#criteria}
+  #
+  class ComponentCriteriaManager < Windoo::BaseClasses::CriteriaManager
+
+    # Constants
+    ######################
+
+    MEMBER_CLASS = Windoo::ComponentCriterion
+
+  end # class RequirementManager
+
+end # Module Windoo

data/lib/windoo/objects/component_criterion.rb

@@ -0,0 +1,66 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+# main module
+module Windoo
+
+  # The class for dealing with the criteria of Patch Components
+  class ComponentCriterion < Windoo::BaseClasses::Criterion
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'criteria'
+
+    CONTAINER_CLASS = Windoo::Component
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute criteriaId
+      # @return [Integer] The id number of this criterion
+      criteriaId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute componentId
+      # @return [Integer] The id number of the component which uses this criterion
+      componentId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      }
+
+    }.freeze
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @criteriaId = post_response[:criteriaId]
+      @componentId = post_response[:componentId]
+      @componentId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(_put_response)
+      @criteriaIds
+    end
+
+  end # class ComponentCriterion
+
+end # module Windoo

data/lib/windoo/objects/extension_attribute.rb

@@ -0,0 +1,149 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+module Windoo
+
+  # The class for dealing with Software Title ExtensionAttributes in the
+  # TitleEditor.
+  #
+  # NOTE: Do not create or delete instances of this class directly.
+  # use:
+  #
+  #   - SoftwareTitle#add_extensionAttribute
+  #     - From {SoftwareTitle#add_extensionAttribute}
+  # and
+  #
+  #   - SoftwareTitle#delete_extensionAttribute
+  #     - From {SoftwareTitle#delete_extensionAttribute}
+  #
+  class ExtensionAttribute < Windoo::BaseClasses::JSONObject
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'extensionattributes'
+
+    CONTAINER_CLASS = Windoo::SoftwareTitle
+
+    # Public Class Methods
+    ######################
+
+    # Override for APICollection.create to deal with raw scripts being
+    # passed in and converted to 'values'
+    def self.create(container: nil, **init_data)
+      if init_data[:script]
+        require 'base64'
+        init_data[:value] = Base64.encode64 init_data[:script]
+        init_data.delete :script
+      end
+
+      super container: container, cnx: container.cnx, **init_data
+    end
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute extensionAttributeId
+      # @return [Integer] The id number of this extension attribute in the Title Editor
+      extensionAttributeId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute softwareTitleId
+      # @return [Integer] The id number of the title which uses this extension attribute
+      softwareTitleId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute key
+      # @return [String] The name of the extension attribute as it appears in Jamf Pro
+      #    NOTE: must be unique in the Title Editor AND Jamf Pro.
+      key: {
+        class: :String,
+        required: true,
+        identifier: true
+      },
+
+      # @!attribute value
+      # @return [String] The Base64 encoded script for this extension attribute
+      value: {
+        class: :String
+      },
+
+      # @!attribute displayName
+      # @return [String] The name of the extension attribute as it appears in Title Editor
+      displayName: {
+        class: :String,
+        required: true
+      }
+
+    }.freeze
+
+    # Construcor
+    ######################
+    def initialize(**init_data)
+      # If we were given a raw script when creating a new
+      # EA, save it here  and we'll process it in #create_on_server
+      @script = init_data[:script]
+
+      super
+    end
+
+    # Public Instance Methods
+    ######################
+
+    # @return [String] The script code for this extension attribute
+    def script
+      return if value.to_s.empty?
+
+      require 'base64'
+      Base64.decode64 value
+    end
+
+    # @param code [String] The script code for this extension attribute
+    # @return [void]
+    def script=(code)
+      raise ArgumentError, 'Code must be a string starting with #!' unless code.to_s.start_with?('#!')
+
+      require 'base64'
+      self.value = Base64.encode64(code)
+    end
+
+    # Private Instance Methods
+    ##########################################
+
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @extensionAttributeId = post_response[:extensionAttributeId]
+      @softwareTitleId = container_id
+      @extensionAttributeId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(_put_response)
+      @extensionAttributeId
+    end
+
+  end # class ExtensionAttribute
+
+end # module Windoo

data/lib/windoo/objects/kill_app.rb

@@ -0,0 +1,92 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Windoo
+
+  # A class representing an Application that cannot be running when
+  # a Patch is installed.
+  #
+  # Patches can contain any number of these, and they are accessed using
+  # a {Windoo::KillAppManager} available from the {Patch#killApps} method.
+  #
+  class KillApp < Windoo::BaseClasses::JSONObject
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'killapps'
+
+    CONTAINER_CLASS = Windoo::Patch
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute killAppId
+      # @return [Integer] The id number of this kill app
+      killAppId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute patchId
+      # @return [Integer] The id number of the patch which uses this
+      #   kill app
+      patchId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute bundleId
+      # @return [String] The bundle id of the app that must be quit
+      #   e.g. com.apple.Safari
+      bundleId: {
+        class: :String,
+        required: true
+      },
+
+      # @!attribute appName
+      # @return [String] The name of the app that must be quit
+      appName: {
+        class: :String,
+        required: true
+      }
+
+    }
+
+    # Private Instance Methods
+    ##########################################
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @killAppId = post_response[:killAppId]
+      @patchId = post_response[:patchId]
+
+      @killAppId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(_put_response)
+      @killAppId
+    end
+
+  end # class KillApp
+
+end # Module Windoo