windoo 1.0.1

data/lib/windoo/base_classes/criterion.rb

@@ -0,0 +1,226 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# main module
+module Windoo
+
+  module BaseClasses
+
+    # The base class for dealing with criteria in Software Titles.
+    #
+    # WARNING: CRITERIA ARE IMMUTABLE. See below for how to deal
+    # with this
+    #
+    # Criteria are individual comparisons or 'filter rules' used  to
+    # identify matching computers, much as they are used for Jamf Smart
+    # Groups or Advanced Searches.
+    #
+    # For example, a single criterion might specify all computers where
+    # the app 'FooBar.app' is installed. Another might specify that
+    # FooBar.app is version 12.3.6, or that the OS is Big Sur or higher.
+    #
+    # In SoftwareTitles, criteria are used in three places:
+    #
+    # - As the 'requirements' of a Software Title.
+    #   Each requrement is one criterion, and the Array of them
+    #   define which computers have any version of the title
+    #   installed. Access to the Array is handled via the
+    #   Windoo::RequirementManager class.
+    #
+    # - As the criteria of the sole 'component' of a Patch.
+    #   A Patch's 'components' is an Array of one item (for historical
+    #   reasons apparently).  That component contains an Array of
+    #   criteria that define which computers have _that specific_
+    #   version of the Patch's Title installed. Access to the Array is
+    #    handled via the  Windoo::ComponentCriteriaManager class.
+    #
+    # - As the 'capabilities' of a Patch.
+    #   Each capability is one criterion, and the Array of them
+    #   define which computers are capable of running, and thus
+    #   allowed to install, this Patch. Access to the Array is handled
+    #   via the Windoo::CapabilitytManager class.
+    #
+    # This class is the superclass of the individual types of criteria
+    # used in the Title Editor. For example Windoo::Requirement is a
+    # subclass of this class.
+    #
+    # Criteria always come in groups (perhaps a group of one) and are
+    # stored in Arrays. However, the arrays are not directly accessible,
+    # but are managed by subclasses of Windoo::CriteriaManager. For
+    # example, the Windoo::Requirement objects of a SoftwareTitle are stored
+    # in an instance of Windoo::RequirementManager.
+    #
+    # These 'managers' provide methods for adding, replacing, moving,
+    # and deleting the individual criteria in the array, and maintain
+    # consistency between the local array and the actual objects stored
+    # on the server.
+    #
+    # CRITERIA ARE IMMUTABLE:
+    #
+    # Criteria are immutable once created, mostly because to modify any of the
+    # primary values of one (name, operator, & value), you have to modify them
+    # all at once or you end up in a chicken/egg situation where the server will
+    # complain of invalid values, which can't easily  be worked around when
+    # updating the values individually.
+    #
+    # Instead of modifying one, delete it and replace it with a new one in the
+    # same position in the array. There's a convenience method for this in the
+    # CriteriaManager called #replace_criterion(id)
+    #
+    # When creating criteria using CriteriaManager#add_criterion, they area added
+    # to the end of the array by default, but you can specify the position using the
+    # absoluteOrderId value. You can also move the position of a criterion in the
+    # array using CriteriaManager#update_criterion method and passing in the new
+    # absoluteOrderId value.
+    #
+    class Criterion < Windoo::BaseClasses::JSONObject
+
+      # Mixins
+      #####################
+
+      extend Windoo::Mixins::Immutable
+
+      # Constants
+      #####################
+
+      # The authoritative list of available types can be read from the API
+      # at GET 'valuelists/criteria/types', or also via
+      # Windoo::BaseClasses::CriteriaManager.available_types
+
+      TYPE_RECON = 'recon'
+      TYPE_EA = 'extensionAttribute'
+
+      TYPES = [TYPE_RECON, TYPE_EA].freeze
+
+      # These attributes must be updated together for Criteria objects
+      ATTRIBUTES_TO_UPDATE_TOGETHER = %i[name operator value].freeze
+
+      # Attributes
+      ######################
+
+      JSON_ATTRIBUTES = {
+
+        # @!attribute absoluteOrderId
+        # @return [Integer] The zero-based position of this requirement among
+        #   all those used by the title. Should be identical to the Array index
+        #   of this requirement in the #requirements attribute of the SoftwareTitle
+        #   instance that uses this requirement
+        absoluteOrderId: {
+          class: :Integer
+        },
+
+        # @!attribute and_or
+        # @return [Symbol] Either :and or :or. This indicates how this criterion is
+        #   joined to the previous one in a chain of boolean logic.
+        #
+        #   NOTE: In the Title Editor JSON data, this key for this value is the
+        #   word "and" and its value is a boolean: if false, the joiner is "or".
+        #   However, because "and" is a reserved word in ruby, we convert that
+        #   value into this one during initialization, and back when sending
+        #   data to the Title Editor.
+        and_or: {
+          class: :Symbol
+        },
+
+        # @!attribute name
+        # @return [String] The name of the criteria to search in this requirement.
+        #    See the API resource GET 'valuelists/criteria/names'
+        name: {
+          class: :String,
+          required: true
+        },
+
+        # @!attribute operator
+        # @return [String] The criteria operator to apply to the criteria name
+        #    See the API resource POST 'valuelists/criteria/names',  {name: 'Criteria Name'}
+        operator: {
+          class: :String,
+          required: true
+        },
+
+        # @!attribute value
+        # @return [Object] The the value to apply with the operator to the named criteria
+        #   We can't specify the class of the value, because it might be a String, Integer, Time, or
+        #   something else.
+        value: {
+          class: :Object
+        },
+
+        # @!attribute type
+        # @return [String] What type of criteria is the named one?
+        #   Must be one of the values in TYPES
+        type: {
+          class: :String,
+          required: true
+        }
+      }.freeze
+
+      # Constructor
+      ######################
+      def initialize(**init_data)
+        super
+        # if #super didn't set @and_or, set it now
+        return unless @and_or.nil?
+
+        @and_or = @init_data[:and] == false ? :or : :and
+      end
+
+      # Public Instance Methods
+      ################################
+
+      # Override handle @and_or before creating
+      #
+      def to_api
+        api_data = super
+        api_data[:and] = (@and_or == :and)
+        api_data.delete :and_or
+        api_data
+      end
+
+      # Allow array managers to change the absoluteOrderId.
+      #
+      # @todo Only allow this to be called from a CriteriaManager.
+      #
+      # @param new_index [Integer] The new, zero-based index for this
+      #   criterion.
+      #
+      # @return [Integer] the id of the updated criterion
+      #
+      def absoluteOrderId=(new_index)
+        new_value = validate_attr :absoluteOrderId, new_index
+        return if new_value == @absoluteOrderId
+
+        update_on_server :absoluteOrderId, new_value
+        @absoluteOrderId = new_value
+      end
+
+      # Update the local absoluteOrderId without updating it on
+      # the server.
+      #
+      # Why??
+      #
+      # Because changing the value on the server for one criterion
+      # using #absoluteOrderId=  will automatically change it on the
+      # server for all the others.
+      #
+      # After changing one on the server and updating that one in the
+      # local array, the CriteriaManager will use this, without
+      # updating the server, to change the value for all others in the
+      # array to match their array index.
+      #
+      # @todo Only allow this to be called from a CriteriaManager.
+      #
+      # @return [void]
+      def local_absoluteOrderId=(new_index)
+        @absoluteOrderId = new_index
+      end
+
+    end # class Criterion
+
+  end # module BaseClasses
+
+end # module Windoo

data/lib/windoo/base_classes/json_object.rb

@@ -0,0 +1,472 @@
+# 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
+
+  module BaseClasses
+
+    # The base class for objects that are instantiated from
+    # a JSON Hash
+    class JSONObject
+
+      # Constants
+      ######################
+
+      # When using prettyprint, don't spit out these instance variables.
+      PP_OMITTED_INST_VARS = %i[@init_data @container @softwareTitle].freeze
+
+      # Attributes
+      ######################
+
+      # @return [Hash] The raw JSON data this object was instantiated with
+      attr_reader :init_data
+
+      # Public Class Methods
+      ######################
+
+      # by default, instances of subclasses are mutable
+      # as a whole (even if some attributes are readonly)
+      # To make them immutable, they should extend
+      # Windoo::Mixins::Immutable, which overrides
+      # this method
+      def self.mutable?
+        true
+      end
+
+      # The merged JSON_ATTRIBUTES Hashes of
+      # any subclass of JSONObject including
+      # all ancestors up to JSONObject itself
+      #
+      # @return [Hash{Symbol => Hash}]
+      ####
+      def self.json_attributes
+        return {} if self == Windoo::BaseClasses::JSONObject
+        return @json_attributes if @json_attributes
+
+        @json_attributes = defined?(self::JSON_ATTRIBUTES) ? self::JSON_ATTRIBUTES.dup : {}
+        @json_attributes.merge! superclass.json_attributes if superclass.respond_to?(:json_attributes)
+        @json_attributes
+      end
+
+      # The attributes that are required to have values.
+      # These must be passed in when calling .create, and must
+      # exist in the instance when calling #save
+      #
+      # @return [Array<Symbol>]
+      ####
+      def self.required_attributes
+        @required_attributes ||= json_attributes.select { |_key, deets| deets[:required] }.keys
+      end
+
+      # @return [Array<Symbol>] the available identifier keys for objects that have them
+      def self.ident_keys
+        return @ident_keys if @ident_keys
+
+        @ident_keys = []
+
+        json_attributes.each do |key, deets|
+          next unless deets[:identifier]
+
+          @primary_id_key = key if deets[:identifier] == :primary
+          @ident_keys << key
+        end
+
+        @ident_keys
+      end
+
+      # @return [Symbol] the key of the primary identifier, if there is one
+      def self.primary_id_key
+        return @primary_id_key if @primary_id_key
+
+        # this method sets @primary_id_key as it loops through json_attributes
+        ident_keys
+        @primary_id_key
+      end
+
+      # create getters and setters for subclasses of JSONObject
+      # based on their JSON_ATTRIBUTES Hash.
+      #
+      # This method can't be private, cuz we want to call it from a
+      # Zeitwerk callback when subclasses are loaded.
+      ##############################
+      def self.parse_json_attributes
+        # nothing to do if JSON_ATTRIBUTES is not defined for this class
+        return unless defined? self::JSON_ATTRIBUTES
+
+        self::JSON_ATTRIBUTES.each do |attr_name, attr_def|
+          if attribute_already_parsed?(attr_name)
+            Windoo.load_msg "Ancestor of #{self} has already parsed attribute #{attr_name}"
+            next
+          end
+
+          Windoo.load_msg "Defining getters and setters for attribute '#{attr_name}' of #{self}"
+
+          # there can be only one (primary ident)
+          if attr_def[:identifier] == :primary
+            raise Windoo::UnsupportedError, 'Two identifiers marked as :primary' if @got_primary
+
+            @got_primary = true
+          end
+
+          # create getter unless the attr is write only
+          define_getters attr_name, attr_def unless attr_def[:writeonly]
+
+          # Don't crete setters for readonly attrs, or immutable objects
+          define_setters attr_name, attr_def if mutable? && !attr_def[:readonly]
+
+          json_attributes_parsed << attr_name
+        end #  do |attr_name, attr_def|
+      end # parse_object_model
+
+      # have we already parsed our JSON_ATTRIBUTES? If so,
+      # we shoudn't do it again, and this can be used to check
+      def self.json_attributes_parsed
+        @json_attributes_parsed ||= []
+      end
+
+      # Used by auto-generated setters and .create to validate new values.
+      #
+      # returns a valid value or raises an exception
+      #
+      # This method only validates single values. When called from multi-value
+      # setters, it is used for each value individually.
+      #
+      # @param attr_name[Symbol], a top-level key from OAPI_PROPERTIES for this class
+      #
+      # @param value [Object] the value to validate for that attribute.
+      #
+      # @return [Object] The validated, possibly converted, value.
+      #
+      def self.validate_attr(attr_name, value)
+        attr_def = json_attributes[attr_name]
+        raise ArgumentError, "Unknown attribute: #{attr_name} for #{self} objects" unless attr_def
+
+        # validate the value based on the OAPI definition.
+        Windoo::Validate.json_attr value, attr_def: attr_def, attr_name: attr_name
+      end # validate_attr(attr_name, value)
+
+      # Private Class Methods
+      #####################################
+
+      # has one of our superclasses already parsed this attribute?
+      ##############################
+      def self.attribute_already_parsed?(attr_name)
+        superclass.respond_to?(:json_attributes_parsed) && superclass.json_attributes_parsed.include?(attr_name)
+      end
+
+      # create a getter for an attribute, and any aliases needed
+      ##############################
+      def self.define_getters(attr_name, attr_def)
+        Windoo.load_msg "..Defining getter method #{self}##{attr_name}"
+
+        define_method(attr_name) { instance_variable_get("@#{attr_name}") }
+
+        # all booleans get predicate ? aliases
+        alias_method("#{attr_name}?", attr_name) if attr_def[:class] == :Boolean
+      end # create getters
+      private_class_method :define_getters
+
+      # create setter for an attribute
+      ##############################
+      def self.define_setters(attr_name, attr_def)
+        # readonly values don't get setters
+        return if attr_def[:readonly]
+
+        Windoo.load_msg "..Defining setter method #{self}##{attr_name}="
+
+        define_method("#{attr_name}=") do |new_value|
+          new_value = validate_attr attr_name, new_value
+          old_value = instance_variable_get("@#{attr_name}")
+          return if new_value == old_value
+
+          # always update the server before the local
+          # value, so server errors will be raised first
+          # But only if this is a server object
+          # and
+          update_on_server(attr_name, new_value) if ok_to_send_to_server?(attr_name)
+
+          instance_variable_set("@#{attr_name}", new_value)
+        end # define method
+      end # define_setters
+      private_class_method :define_setters
+
+      ##############################
+      # def self.create_array_setters(attr_name, attr_def)
+      #   create_full_array_setters(attr_name, attr_def)
+      #   create_append_setters(attr_name, attr_def)
+      #   create_prepend_setters(attr_name, attr_def)
+      #   create_insert_setters(attr_name, attr_def)
+      #   create_delete_setters(attr_name, attr_def)
+      #   create_delete_at_setters(attr_name, attr_def)
+      #   create_delete_if_setters(attr_name, attr_def)
+      # end # def create_multi_setters
+      # private_class_method :create_array_setters
+
+      # The  attr=(newval) setter method for array values
+      # ##############################
+      # def self.create_full_array_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}="
+
+      #   define_method("#{attr_name}=") do |new_value|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     raise Windoo::InvalidDataError, "Value for '#{attr_name}=' must be an Array" unless new_value.is_a? Array
+
+      #     # validate each item of the new array
+      #     new_value.map! { |item| validate_attr attr_name, item }
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_value, attr_def: attr_def, attr_name: attr_name)
+
+      #     old_value = instance_variable_get("@#{attr_name}")
+      #     return if new_value == old_value
+
+      #     instance_variable_set("@#{attr_name}", new_value)
+      #   end # define method
+
+      #   return unless attr_def[:aliases]
+      # end # create_full_array_setter
+      # private_class_method :create_full_array_setters
+
+      # The  attr_append(newval) setter method for array values
+      ##############################
+      # def self.create_append_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_append"
+
+      #   define_method("#{attr_name}_append") do |new_value|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_value = validate_attr attr_name, new_value
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     new_array << new_value
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+
+      #   # always have a << alias
+      #   alias_method "#{attr_name}<<", "#{attr_name}_append"
+      # end # create_append_setters
+      # private_class_method :create_append_setters
+
+      # The  attr_prepend(newval) setter method for array values
+      ##############################
+      # def self.create_prepend_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_prepend"
+
+      #   define_method("#{attr_name}_prepend") do |new_value|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_value = validate_attr attr_name, new_value
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     new_array.unshift new_value
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+      # end # create_prepend_setters
+      # private_class_method :create_prepend_setters
+
+      # The  attr_insert(index, newval) setter method for array values
+      # def self.create_insert_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_insert"
+
+      #   define_method("#{attr_name}_insert") do |index, new_value|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_value = validate_attr attr_name, new_value
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     new_array.insert index, new_value
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+      # end # create_insert_setters
+      # private_class_method :create_insert_setters
+
+      # The  attr_delete(val) setter method for array values
+      ##############################
+      # def self.create_delete_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_delete"
+
+      #   define_method("#{attr_name}_delete") do |val|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     new_array.delete val
+      #     return if old_array == new_array
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+      # end # create_insert_setters
+      # private_class_method :create_delete_setters
+
+      # The  attr_delete_at(index) setter method for array values
+      ##############################
+      # def self.create_delete_at_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_delete_at"
+
+      #   define_method("#{attr_name}_delete_at") do |index|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     deleted = new_array.delete_at index
+      #     return unless deleted
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+      # end # create_insert_setters
+      # private_class_method :create_delete_at_setters
+
+      # The  attr_delete_if(block) setter method for array values
+      ##############################
+      # def self.create_delete_if_setters(attr_name, attr_def)
+      #   Windoo.load_msg "Creating multi-value setter method #{self}##{attr_name}_delete_if"
+
+      #   define_method("#{attr_name}_delete_if") do |&block|
+      #     initialize_multi_value_attr_array attr_name
+
+      #     new_array = instance_variable_get("@#{attr_name}")
+      #     old_array = new_array.dup
+      #     new_array.delete_if(&block)
+      #     return if old_array == new_array
+
+      #     # now validate the array as a whole for oapi constraints
+      #     Windoo::Validate.array_constraints(new_array, attr_def: attr_def, attr_name: attr_name)
+      #   end # define method
+      # end # create_insert_setters
+      # private_class_method :create_delete_if_setters
+
+      # Constructor
+      ######################
+      def initialize(**init_data)
+        @init_data = init_data
+        @init_data.each do |key, val|
+          next unless self.class.json_attributes.key? key
+
+          # The inst var is always a dup of the init_data, so that
+          # changes to it don't affect the init data.
+          ruby_val =
+            if val && self.class.json_attributes[key][:to_ruby]
+              Windoo::Converters.send self.class.json_attributes[key][:to_ruby], val.dup
+            else
+              val.dup
+            end
+
+          instance_variable_set "@#{key}", ruby_val
+        end
+      end
+
+      # Public Instance Methods
+      #####################
+
+      # @return [Hash] The data to be sent to the API, as a Hash
+      #  to be converted to JSON before sending to the JPAPI
+      #
+      #  This is currently only used when creating new objects in the API.
+      #  Updates happen immediately per attribute, from the setter methods,
+      #  sending only the new value to the server.
+      #
+      #  It might also be used in the future to export JSON title
+      #  definitions to import into other Title Servers.
+      #
+      def to_api
+        api_data = {}
+        attrs_for_save = self.class.json_attributes.keys
+
+        attrs_for_save.each do |attr_name|
+          attr_def = self.class.json_attributes[attr_name]
+          next if attr_def[:do_not_send]
+
+          raw_value = instance_variable_get "@#{attr_name}"
+
+          api_data[attr_name] =
+            if raw_value.nil?
+              nil
+            else
+              single_to_api(raw_value, attr_def)
+            end
+        end
+        api_data
+      end
+
+      # @return [String] the JSON to be sent to the API for this
+      #   object
+      #
+      #  This is only used when creating new objects in the API.
+      #  Updates happen immediately from the setter methods,
+      #  sending only the new value to the server.
+      #
+      def to_json(*_args)
+        JSON.pretty_generate to_api
+      end
+
+      # Only selected items are displayed with prettyprint
+      # otherwise its too much data in irb.
+      #
+      # @return [Array] the desired instance_variables
+      #
+      def pretty_print_instance_variables
+        instance_variables - PP_OMITTED_INST_VARS
+      end
+
+      # Private Instance Methods
+      #####################################
+      private
+
+      # should an attribute be sent to the server when running the setter?
+      # Only if its an APICollection, and the attribute is not 'do_not_send'
+      def ok_to_send_to_server?(attr_name)
+        self.class.ancestors.include?(Windoo::Mixins::APICollection) && \
+          !self.class.json_attributes.dig(attr_name, :do_not_send)
+      end
+
+      # Initialize a multi-values attribute as an empty array
+      # if it hasn't been created yet
+      def initialize_multi_value_attr_array(attr_name)
+        return if instance_variable_get("@#{attr_name}").is_a? Array
+
+        instance_variable_set("@#{attr_name}", [])
+      end
+
+      # wrapper for class method
+      def validate_attr(attr_name, value)
+        self.class.validate_attr attr_name, value
+      end
+
+      # call to_api on a single value if it knows that method
+      # or pass it to the converter module if needed
+      # otherwise, the value is good as is
+      def single_to_api(raw_value, attr_def)
+        if attr_def[:to_api]
+          Windoo::Converters.send attr_def[:to_api], raw_value.dup
+        elsif raw_value.respond_to?(:to_api)
+          raw_value.to_api
+        else
+          raw_value
+        end
+      end
+
+      # Call to_api on an array value
+      #
+      def multi_to_api(raw_array, attr_def)
+        raw_array ||= []
+        raw_array.map { |raw_value| single_to_api(raw_value, attr_def) }.compact
+      end
+
+    end # class JSONObject
+
+  end # module BaseClasses
+
+end # module Windoo