command_tower 0.3.1 → 0.10.0

data/app/services/command_tower/messaging/planner/planner.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Planner
+      class Planner
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(
+          notification_type_key:,
+          recipient_id:,
+          preference_state: nil,
+          platform_enabled_channels: [],
+          message_overrides: nil
+        )
+          @notification_type_key = notification_type_key.to_s
+          @recipient_id = recipient_id
+          @preference_state = preference_state
+          @platform_enabled_channels = Array(platform_enabled_channels).map(&:to_s)
+          @message_overrides = MessageOverrides.normalize(message_overrides)
+        end
+
+        def call
+          unless @preference_state.nil?
+            raise InvalidEvaluationError,
+                  "preference_state must not be supplied to Planner; use Preferences::Store"
+          end
+
+          declaration = lookup_declaration!
+          evaluation = evaluate_preferences!
+          readiness = evaluate_readiness!
+
+          selected_channels = declaration.default_channels.select do |channel|
+            evaluation.permitted_channels.include?(channel)
+          end
+          inbox_selected = declaration.inbox_available && evaluation.inbox_permitted
+
+          excluded = build_initial_exclusions(
+            declaration:,
+            evaluation:,
+            selected_channels:,
+            inbox_selected:,
+          )
+
+          selected_channels, excluded = apply_readiness_intersection(
+            selected_channels:,
+            excluded:,
+            readiness:,
+          )
+
+          selected_channels, inbox_selected, excluded =
+            apply_overrides(
+              declaration:,
+              evaluation:,
+              readiness:,
+              selected_channels:,
+              inbox_selected:,
+              excluded:,
+            )
+
+          if declaration.mandatory && selected_channels.empty? && !inbox_selected
+            raise ImpossibleMandatoryPlanError,
+                  "mandatory notification type has no selectable destinations: #{@notification_type_key}"
+          end
+
+          DestinationPlan.build(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            selected_channels:,
+            inbox_selected:,
+            excluded_destinations: excluded,
+            mandatory: declaration.mandatory,
+            preference_evaluation: evaluation,
+          )
+        end
+
+        private
+
+        def lookup_declaration!
+          NotificationTypes.lookup(@notification_type_key)
+        rescue NotificationTypes::NotFoundError
+          raise UnknownTypeError, "notification type not registered: #{@notification_type_key}"
+        end
+
+        def evaluate_preferences!
+          result = Preferences.resolve(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            platform_enabled_channels: @platform_enabled_channels,
+          )
+
+          unless result.is_a?(Preferences::EvaluationResult)
+            raise InvalidEvaluationError, "preference evaluation did not return EvaluationResult"
+          end
+
+          result
+        rescue Preferences::UnknownTypeError
+          raise UnknownTypeError, "notification type not registered: #{@notification_type_key}"
+        rescue Preferences::InvalidPreferenceStateError => e
+          raise InvalidEvaluationError, e.message
+        rescue Preferences::StoreError => e
+          raise InvalidEvaluationError, e.message
+        end
+
+        def evaluate_readiness!
+          RecipientReadiness.for_recipient(
+            recipient_id: @recipient_id,
+            platform_enabled_channels: @platform_enabled_channels,
+          )
+        rescue RecipientReadiness::RecipientNotFoundError => e
+          raise InvalidEvaluationError, e.message
+        end
+
+        def apply_readiness_intersection(selected_channels:, excluded:, readiness:)
+          ready_keys = readiness.ready_channel_keys
+          selected = selected_channels.dup
+          excluded = excluded.dup
+
+          selected_channels.each do |channel|
+            next if ready_keys.include?(channel)
+
+            selected.delete(channel)
+            exclude_for_unreadiness!(excluded:, channel:, readiness:)
+          end
+
+          [selected, excluded]
+        end
+
+        def exclude_for_unreadiness!(excluded:, channel:, readiness:)
+          channel_result = readiness.channel(channel)
+          reason_codes = Array(channel_result&.reason_codes)
+          reason =
+            reason_codes.first || RecipientReadiness::ReasonCodes::IDENTITY_UNAVAILABLE
+
+          excluded.reject! { |item| item.destination == channel }
+          excluded << ExcludedDestination.build(
+            destination: channel,
+            reason_class: reason,
+          )
+
+          OperationLogger.readiness_excluded(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            channel_key: channel,
+            reason_codes:,
+          )
+        end
+
+        def build_initial_exclusions(declaration:, evaluation:, selected_channels:, inbox_selected:)
+          excluded = []
+
+          evaluation.suppressed_destinations.each do |suppressed|
+            next if suppressed.destination == :inbox && inbox_selected
+            next if selected_channels.include?(suppressed.destination)
+
+            excluded << ExcludedDestination.build(
+              destination: suppressed.destination,
+              reason_class: suppressed.reason_class,
+            )
+          end
+
+          declaration.allowed_channels.each do |channel|
+            next if selected_channels.include?(channel)
+            next if excluded.any? { |item| item.destination == channel }
+
+            if evaluation.permitted_channels.include?(channel)
+              excluded << ExcludedDestination.build(
+                destination: channel,
+                reason_class: Preferences::ReasonClasses::SKIPPED_BY_POLICY,
+              )
+            end
+          end
+
+          if declaration.inbox_available && !inbox_selected
+            unless excluded.any? { |item| item.destination == :inbox }
+              reason =
+                evaluation.suppressed_destinations.find { |item| item.destination == :inbox }&.reason_class ||
+                Preferences::ReasonClasses::SKIPPED_BY_POLICY
+
+              excluded << ExcludedDestination.build(
+                destination: :inbox,
+                reason_class: reason,
+              )
+            end
+          end
+
+          excluded
+        end
+
+        def apply_overrides(
+          declaration:,
+          evaluation:,
+          readiness:,
+          selected_channels:,
+          inbox_selected:,
+          excluded:
+        )
+          return [selected_channels, inbox_selected, excluded] if @message_overrides.nil?
+
+          overrides = @message_overrides
+          selected = selected_channels.dup
+          excluded = excluded.dup
+          ready_keys = readiness.ready_channel_keys
+
+          overrides.channels_add.each do |channel|
+            unless declaration.allowed_channels.include?(channel)
+              raise IllegalOverrideError, "override cannot add channel outside allowed set: #{channel}"
+            end
+
+            unless evaluation.permitted_channels.include?(channel)
+              raise IllegalOverrideError, "override cannot add channel not permitted by preferences: #{channel}"
+            end
+
+            unless ready_keys.include?(channel)
+              raise IllegalOverrideError,
+                    "override cannot add channel that is not recipient-ready: #{channel}"
+            end
+
+            next if selected.include?(channel)
+
+            selected << channel
+            excluded.reject! { |item| item.destination == channel }
+          end
+
+          overrides.channels_remove.each do |channel|
+            selected.delete(channel)
+            next if excluded.any? { |item| item.destination == channel }
+
+            excluded << ExcludedDestination.build(
+              destination: channel,
+              reason_class: Preferences::ReasonClasses::SKIPPED_BY_POLICY,
+            )
+          end
+
+          unless overrides.inbox.nil?
+            if overrides.inbox
+              unless declaration.inbox_available && evaluation.inbox_permitted
+                raise IllegalOverrideError, "override cannot select inbox when not available/permitted"
+              end
+
+              inbox_selected = true
+              excluded.reject! { |item| item.destination == :inbox }
+            else
+              inbox_selected = false
+              unless excluded.any? { |item| item.destination == :inbox }
+                excluded << ExcludedDestination.build(
+                  destination: :inbox,
+                  reason_class: Preferences::ReasonClasses::SKIPPED_BY_POLICY,
+                )
+              end
+            end
+          end
+
+          [selected, inbox_selected, excluded]
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/planner/unknown_type_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Planner
+      class UnknownTypeError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/planner.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Planner
+      module_function
+
+      def plan(
+        notification_type_key:,
+        recipient_id:,
+        preference_state: nil,
+        platform_enabled_channels: [],
+        message_overrides: nil
+      )
+        ::CommandTower::Messaging::Planner::Planner.call(
+          notification_type_key:,
+          recipient_id:,
+          preference_state:,
+          platform_enabled_channels:,
+          message_overrides:,
+        )
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/catalog.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Catalog
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(recipient_id:, platform_enabled_channels: [])
+          @recipient_id = recipient_id
+          @platform_enabled_channels = Array(platform_enabled_channels).map(&:to_s).freeze
+        end
+
+        def call
+          recipient_ready_keys = recipient_ready_channel_keys
+          categories = []
+
+          NotificationTypes.catalog.each do |category|
+            notifications = []
+
+            category.declarations.each do |declaration|
+              next unless declaration.settings_visible
+
+              evaluation = Resolve.call(
+                notification_type_key: declaration.key,
+                recipient_id: @recipient_id,
+                platform_enabled_channels: @platform_enabled_channels,
+              )
+
+              notifications << build_notification(declaration, evaluation, recipient_ready_keys)
+            end
+
+            next if notifications.empty?
+
+            categories << ::CommandTower::Messaging::Preferences::CatalogCategoryResult.build(
+              key: category.key,
+              label: category.label,
+              description: nil,
+              order: category.order,
+              notifications:,
+            )
+          end
+
+          ::CommandTower::Messaging::Preferences::CatalogResult.build(categories:)
+        end
+
+        private
+
+        def recipient_ready_channel_keys
+          RecipientReadiness.for_recipient(
+            recipient_id: @recipient_id,
+            platform_enabled_channels: @platform_enabled_channels,
+          ).recipient_ready_channel_keys
+        rescue RecipientReadiness::RecipientNotFoundError
+          []
+        end
+
+        def build_notification(declaration, evaluation, recipient_ready_keys)
+          effective_state = evaluation.effective_preference_state || {}
+          effective_channels = effective_state["channels"] || {}
+          channels =
+            declaration.allowed_channels.to_h do |channel|
+              [channel, !!effective_channels[channel]]
+            end
+
+          inbox_enabled =
+            if effective_state.key?("inbox")
+              !!effective_state["inbox"]
+            else
+              evaluation.inbox_permitted
+            end
+
+          available =
+            declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
+
+          ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
+            key: declaration.key,
+            label: declaration.label,
+            description: declaration.description,
+            order: declaration.type_order,
+            configurable: declaration.user_configurable,
+            mandatory: declaration.mandatory,
+            inbox_available: declaration.inbox_available,
+            allowed_channels: declaration.allowed_channels,
+            available_channels: available,
+            inbox_enabled:,
+            channels:,
+            stored_override_present: evaluation.stored_override_present,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/catalog_category_result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      CatalogCategoryResult = Data.define(:key, :label, :description, :order, :notifications) do
+        def self.build(key:, label:, description:, order:, notifications:)
+          new(
+            key: key.to_s,
+            label: label.to_s,
+            description:,
+            order: Integer(order),
+            notifications: Array(notifications).freeze,
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/catalog_notification_result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      CatalogNotificationResult = Data.define(
+        :key,
+        :label,
+        :description,
+        :order,
+        :configurable,
+        :mandatory,
+        :inbox_available,
+        :allowed_channels,
+        :available_channels,
+        :inbox_enabled,
+        :channels,
+        :stored_override_present,
+      ) do
+        def self.build(
+          key:,
+          label:,
+          description:,
+          order:,
+          configurable:,
+          mandatory:,
+          inbox_available:,
+          allowed_channels:,
+          available_channels:,
+          inbox_enabled:,
+          channels:,
+          stored_override_present:
+        )
+          frozen_channels =
+            channels.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
+
+          new(
+            key: key.to_s,
+            label: label.to_s,
+            description:,
+            order: Integer(order),
+            configurable: !!configurable,
+            mandatory: !!mandatory,
+            inbox_available: !!inbox_available,
+            allowed_channels: Array(allowed_channels).map(&:to_s).freeze,
+            available_channels: Array(available_channels).map(&:to_s).freeze,
+            inbox_enabled: !!inbox_enabled,
+            channels: frozen_channels,
+            stored_override_present: !!stored_override_present,
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/catalog_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      CatalogResult = Data.define(:categories) do
+        def self.build(categories:)
+          new(categories: Array(categories).freeze).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Error < CommandTower::Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences/evaluation_result.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      EvaluationResult = Data.define(
+        :notification_type_key,
+        :recipient_id,
+        :permitted_channels,
+        :inbox_permitted,
+        :suppressed_destinations,
+        :mandatory,
+        :mandatory_enforced,
+        :stored_override_present,
+        :effective_preference_state,
+      ) do
+        def self.build(
+          notification_type_key:,
+          recipient_id:,
+          permitted_channels:,
+          inbox_permitted:,
+          suppressed_destinations:,
+          mandatory:,
+          mandatory_enforced:,
+          stored_override_present: false,
+          effective_preference_state: nil
+        )
+          new(
+            notification_type_key: notification_type_key.to_s,
+            recipient_id:,
+            permitted_channels: Array(permitted_channels).map(&:to_s).freeze,
+            inbox_permitted: !!inbox_permitted,
+            suppressed_destinations: Array(suppressed_destinations).freeze,
+            mandatory: !!mandatory,
+            mandatory_enforced: !!mandatory_enforced,
+            stored_override_present: !!stored_override_present,
+            effective_preference_state: freeze_effective_state(effective_preference_state),
+          ).freeze
+        end
+
+        def self.freeze_effective_state(state)
+          return nil if state.nil?
+
+          hash = state.to_h.transform_keys(&:to_s)
+          channels = hash["channels"]
+          frozen_channels =
+            if channels.nil?
+              {}.freeze
+            else
+              channels.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
+            end
+
+          result = { "channels" => frozen_channels }
+          result["inbox"] = !!hash["inbox"] if hash.key?("inbox")
+          result.freeze
+        end
+        private_class_method :freeze_effective_state
+      end
+    end
+  end
+end