command_tower 0.18.0 → 0.19.0

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

@@ -16,6 +16,8 @@ module CommandTower
         :inbox_enabled,
         :channels,
         :stored_override_present,
+        :urgency,
+        :sound,
       ) do
         def self.build(
           key:,
@@ -29,7 +31,9 @@ module CommandTower
           available_channels:,
           inbox_enabled:,
           channels:,
-          stored_override_present:
+          stored_override_present:,
+          urgency:,
+          sound:
         )
           frozen_channels =
             channels.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
@@ -47,8 +51,29 @@ module CommandTower
             inbox_enabled: !!inbox_enabled,
             channels: frozen_channels,
             stored_override_present: !!stored_override_present,
+            urgency: freeze_block(urgency),
+            sound: freeze_block(sound),
           ).freeze
         end
+
+        def self.freeze_block(block)
+          hash = block.to_h
+          allowed = hash[:allowed]
+          frozen_allowed =
+            if allowed.is_a?(Array) && allowed.first.is_a?(Hash)
+              allowed.map { |entry| entry.to_h.transform_keys(&:to_sym).freeze }.freeze
+            else
+              Array(allowed).map(&:to_s).freeze
+            end
+
+          {
+            default: hash[:default].to_s,
+            allowed: frozen_allowed,
+            selectable: !!hash[:selectable],
+            effective: hash[:effective].to_s,
+          }.freeze
+        end
+        private_class_method :freeze_block
       end
     end
   end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      # Resolves the urgency and sound a member actually gets, and the blocks
+      # the preferences API returns. IOS reads this at send time. It does not send.
+      class EffectiveChoice
+        def self.call(declaration:, stored:)
+          new(declaration:, stored:).call
+        end
+
+        def self.urgency_ids(choice)
+          choice.permitted(NotificationTypes::URGENCY_LEVELS)
+        end
+
+        def self.sound_ids(choice)
+          ids = choice.allowed == "all" ? SoundCatalog.ids : Array(choice.allowed)
+          ids.select { |id| SoundCatalog.fetch(id) }
+        end
+
+        def self.selectable?(ids)
+          ids.size > 1
+        end
+
+        def self.validate_write!(declaration:, field:, value:)
+          choice = declaration.public_send(field)
+          ids = field == :urgency ? urgency_ids(choice) : sound_ids(choice)
+          unless value.is_a?(String) && !value.strip.empty?
+            raise InvalidPreferenceStateError, "preference #{field} must be a string"
+          end
+          unless selectable?(ids)
+            raise InvalidPreferenceWriteError, "#{field} is not selectable for notification type: #{declaration.key}"
+          end
+          return if ids.include?(value)
+
+          raise InvalidPreferenceWriteError, "#{field} is not permitted: #{value}"
+        end
+
+        def initialize(declaration:, stored:)
+          @declaration = declaration
+          @stored = stored
+        end
+
+        def call
+          {
+            urgency: urgency_block,
+            sound: sound_block,
+          }
+        end
+
+        private
+
+        def urgency_block
+          choice = @declaration.urgency
+          ids = self.class.urgency_ids(choice)
+          {
+            default: choice.default,
+            allowed: ids,
+            selectable: self.class.selectable?(ids),
+            effective: resolve(stored: @stored&.urgency, ids:, fallback: choice.default),
+          }
+        end
+
+        def sound_block
+          choice = @declaration.sound
+          ids = self.class.sound_ids(choice)
+          {
+            default: choice.default,
+            allowed: ids.map { |id| { id:, label: SoundCatalog.fetch(id)[:label] } },
+            selectable: self.class.selectable?(ids),
+            effective: resolve_sound(ids, choice.default),
+          }
+        end
+
+        def resolve(stored:, ids:, fallback:)
+          return stored if stored && ids.include?(stored)
+
+          fallback
+        end
+
+        def resolve_sound(ids, fallback)
+          stored = @stored&.sound
+          return stored if stored && ids.include?(stored)
+          return fallback if ids.include?(fallback)
+
+          SoundCatalog::SYSTEM_DEFAULT[:id]
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module CommandTower
   module Messaging
     module Preferences
-      PreferenceState = Data.define(:channels, :inbox) do
+      PreferenceState = Data.define(:channels, :inbox, :urgency, :sound) do
         def self.normalize(raw)
           return nil if raw.nil?
 
@@ -31,17 +31,35 @@ module CommandTower
 
           inbox = hash.key?("inbox") ? !!hash["inbox"] : nil
 
-          new(channels:, inbox:).freeze
+          new(
+            channels:,
+            inbox:,
+            urgency: optional_string(hash["urgency"]),
+            sound: optional_string(hash["sound"]),
+          ).freeze
         end
 
         def self.from_declaration_default(default_preference_state)
-          normalize(default_preference_state) || new(channels: {}.freeze, inbox: nil).freeze
+          normalize(default_preference_state) || new(channels: {}.freeze, inbox: nil, urgency: nil, sound: nil).freeze
         end
 
+        def self.optional_string(value)
+          return nil unless value.is_a?(String)
+
+          stripped = value.strip
+          stripped.empty? ? nil : stripped
+        end
+        private_class_method :optional_string
+
         def merge_over(base)
           merged_channels = base.channels.merge(channels)
           merged_inbox = inbox.nil? ? base.inbox : inbox
-          self.class.new(channels: merged_channels.freeze, inbox: merged_inbox).freeze
+          self.class.new(
+            channels: merged_channels.freeze,
+            inbox: merged_inbox,
+            urgency: urgency.nil? ? base.urgency : urgency,
+            sound: sound.nil? ? base.sound : sound,
+          ).freeze
         end
 
         def channel_enabled?(channel_key, default: true)
@@ -53,6 +71,8 @@ module CommandTower
         def to_raw_hash
           hash = { "channels" => channels.to_h }
           hash["inbox"] = inbox unless inbox.nil?
+          hash["urgency"] = urgency unless urgency.nil?
+          hash["sound"] = sound unless sound.nil?
           hash
         end
       end

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

@@ -35,6 +35,10 @@ module CommandTower
           declaration = lookup_declaration!(key)
           validate_writable!(declaration)
 
+          raw = preference_state.to_h.transform_keys(&:to_s)
+          validate_choice!(declaration, raw, "urgency")
+          validate_choice!(declaration, raw, "sound")
+
           normalized = PreferenceState.normalize(preference_state)
           if normalized.nil?
             raise InvalidPreferenceWriteError, "preference_state must be present"
@@ -86,6 +90,12 @@ module CommandTower
                 "preference channels outside allowed set: #{extras.join(', ')}"
         end
 
+        def validate_choice!(declaration, raw, field)
+          return unless raw.key?(field)
+
+          EffectiveChoice.validate_write!(declaration:, field: field.to_sym, value: raw[field])
+        end
+
         def validate_inbox!(declaration, normalized)
           return if normalized.inbox.nil?
           return if declaration.inbox_available

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

@@ -85,7 +85,7 @@ module CommandTower
           end
 
           hash = @preference_state.to_h.transform_keys(&:to_s)
-          unknown_keys = hash.keys - %w[channels inbox]
+          unknown_keys = hash.keys - %w[channels inbox urgency sound]
           if unknown_keys.any?
             raise InvalidPreferenceWriteError,
                   "unsupported preference keys: #{unknown_keys.join(', ')}"
@@ -94,7 +94,12 @@ module CommandTower
           channels = parse_channels!(declaration, hash["channels"])
           inbox = parse_inbox!(declaration, hash)
 
-          PreferenceState.new(channels: channels.freeze, inbox:).freeze
+          PreferenceState.new(
+            channels: channels.freeze,
+            inbox:,
+            urgency: parse_choice!(declaration, hash, "urgency"),
+            sound: parse_choice!(declaration, hash, "sound"),
+          ).freeze
         end
 
         def parse_channels!(declaration, channels_raw)
@@ -136,6 +141,13 @@ module CommandTower
           hash["inbox"]
         end
 
+        def parse_choice!(declaration, hash, field)
+          return nil unless hash.key?(field)
+
+          EffectiveChoice.validate_write!(declaration:, field: field.to_sym, value: hash[field])
+          hash[field].strip
+        end
+
         def sparsify(declaration, candidate)
           defaults = PreferenceState.from_declaration_default(declaration.default_preference_state)
           sparse_channels = {}
@@ -154,9 +166,22 @@ module CommandTower
               candidate.inbox
             end
 
-          return nil if sparse_channels.empty? && sparse_inbox.nil?
+          sparse_urgency = sparse_choice(candidate.urgency, declaration.urgency.default)
+          sparse_sound = sparse_choice(candidate.sound, declaration.sound.default)
+          return nil if sparse_channels.empty? && sparse_inbox.nil? && sparse_urgency.nil? && sparse_sound.nil?
+
+          PreferenceState.new(
+            channels: sparse_channels.freeze,
+            inbox: sparse_inbox,
+            urgency: sparse_urgency,
+            sound: sparse_sound,
+          ).freeze
+        end
+
+        def sparse_choice(value, default)
+          return nil if value.nil? || value == default
 
-          PreferenceState.new(channels: sparse_channels.freeze, inbox: sparse_inbox).freeze
+          value
         end
 
         def persist_reset!
@@ -227,6 +252,11 @@ module CommandTower
           available =
             declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
 
+          blocks = EffectiveChoice.call(
+            declaration:,
+            stored: Store.find(recipient_id: @recipient_id, notification_type_key: @notification_type_key),
+          )
+
           ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
             key: declaration.key,
             label: declaration.label,
@@ -240,6 +270,8 @@ module CommandTower
             inbox_enabled:,
             channels:,
             stored_override_present: evaluation.stored_override_present,
+            urgency: blocks[:urgency],
+            sound: blocks[:sound],
           )
         end
       end

data/app/services/command_tower/messaging/rendering/channel_renderer.rb

@@ -14,11 +14,12 @@ module CommandTower
         TEMPLATE_FILENAME_PATTERN = /\A(?<basename>[a-z]+)\.(?<format>html|text)\.erb\z/
         DEFAULT_TITLE = "Notification"
 
-        def self.render(communication:, channel_key:, recipient_address:)
+        def self.render(communication:, channel_key:, recipient_address:, channel_delivery: nil)
           new(
             communication:,
             channel_key:,
             recipient_address:,
+            channel_delivery:,
           ).render
         end
 
@@ -26,10 +27,11 @@ module CommandTower
           SUPPORTED_CHANNELS.include?(channel_key.to_s)
         end
 
-        def initialize(communication:, channel_key:, recipient_address:)
+        def initialize(communication:, channel_key:, recipient_address:, channel_delivery: nil)
           @communication = communication
           @channel_key = channel_key.to_s
           @recipient_address = recipient_address
+          @channel_delivery = channel_delivery
         end
 
         def render
@@ -98,11 +100,18 @@ module CommandTower
           body = render_template("push.text.erb").to_s.strip
           raise ArgumentError, "body is required" if body.empty?
 
+          deep_link = resolve_push_deep_link
+          presentation = PushPresentation.call(communication: @communication, channel_delivery: @channel_delivery)
+
           RenderedPushPayload.build(
             recipient_address: address,
             title:,
             body:,
-            deep_link: template_locals[:deep_link],
+            deep_link:,
+            sound: presentation.sound,
+            urgency: presentation.urgency,
+            thread_id: presentation.thread_id,
+            badge: presentation.badge,
           )
         end
 
@@ -164,6 +173,57 @@ module CommandTower
           deep_link.presence
         end
 
+        # Metadata deep_link wins. A live inbox item is a destination by itself.
+        # Otherwise substitute the host Home link. Never invent a link.
+        def resolve_push_deep_link
+          existing = deep_link_from_metadata
+          return existing if existing
+          return nil if live_inbox_item
+
+          home = CommandTower.config.messaging.expo.resolve_home_deep_link
+          if home.nil?
+            log_push_destination_fallback(reason_code: "home_deep_link_unresolved", level: :error)
+            raise RenderError.new(code: "render_failed", error_class: "HomeDeepLinkUnresolved")
+          end
+
+          if inbox_preference_disabled?
+            log_push_destination_fallback(reason_code: "inbox_disabled", level: :info)
+          else
+            log_push_destination_fallback(reason_code: "destination_missing", level: :error)
+          end
+          home
+        end
+
+        def live_inbox_item
+          item = @communication.inbox_item
+          return nil unless item&.live_for_push?
+
+          item
+        end
+
+        def inbox_preference_disabled?
+          decision = @communication.destination_plan&.decision
+          return false unless decision.is_a?(Hash)
+
+          excluded = decision["excluded_destinations"] || decision[:excluded_destinations]
+          Array(excluded).any? do |item|
+            next false unless item.is_a?(Hash)
+
+            destination = (item["destination"] || item[:destination]).to_s
+            reason = (item["reason_class"] || item[:reason_class]).to_s
+            destination == "inbox" && reason == Preferences::ReasonClasses::SUPPRESSED_BY_PREFERENCE
+          end
+        end
+
+        def log_push_destination_fallback(reason_code:, level:)
+          Execution::OperationLogger.push_destination_fallback(
+            communication: @communication,
+            reason_code:,
+            level:,
+            channel_delivery: @channel_delivery,
+          )
+        end
+
         def frozen_metadata
           metadata = @communication.metadata
           return {}.freeze unless metadata.is_a?(Hash)

data/app/services/command_tower/messaging/rendering/inbox_document.rb

@@ -92,6 +92,16 @@ module CommandTower
             self
           end
 
+          # ISO-8601 instant with an explicit offset, stored as UTC. Blank,
+          # unparseable, and offset-less values add no block.
+          def instant(at)
+            utc = normalized_instant(at)
+            return self unless utc
+
+            @blocks << { type: "instant", at: utc.iso8601 }.freeze
+            self
+          end
+
           def blocks
             @blocks
           end
@@ -116,6 +126,23 @@ module CommandTower
             path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
           end
 
+          EXPLICIT_ZONE_ISO = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+          def normalized_instant(at)
+            case at
+            when Time
+              at.getutc
+            when String
+              stripped = at.strip
+              return nil if stripped.empty?
+              return nil unless EXPLICIT_ZONE_ISO.match?(stripped)
+
+              Time.iso8601(stripped).getutc
+            end
+          rescue ArgumentError
+            nil
+          end
+
           def safe_href?(href)
             return false unless href.is_a?(String) && !href.strip.empty?
 

data/app/services/command_tower/messaging/rendering/push_presentation.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Resolves how a push should present itself, in provider-neutral terms: the member's
+      # effective urgency, the sound asset (nil for System Default), the conversation
+      # thread, and, for a badge-eligible type, the recipient's current badge-eligible
+      # unread count. Reads the member's stored preference once. Reads the unread count
+      # once, through Messaging::Inbox, only when the declaration is badge-eligible.
+      # The provider adapter maps the result to its own fields. Never raises for an
+      # unregistered type or an unreadable preference: it returns defaults and records
+      # a fallback diagnostic instead. An eligible type keeps its badge on that
+      # preference fallback. Any other error, including a count failure, surfaces.
+      class PushPresentation
+        Result = Data.define(:urgency, :sound, :thread_id, :badge)
+
+        DEFAULT_URGENCY = "normal"
+
+        def self.call(communication:, channel_delivery: nil)
+          new(communication:, channel_delivery:).call
+        end
+
+        def initialize(communication:, channel_delivery: nil)
+          @communication = communication
+          @channel_delivery = channel_delivery
+        end
+
+        def call
+          declaration = NotificationTypes.lookup(@communication.notification_type_key)
+          badge = badge_count(declaration)
+          blocks = Preferences::EffectiveChoice.call(declaration:, stored: stored_state(declaration))
+
+          build(
+            urgency: blocks.dig(:urgency, :effective),
+            sound: sound_asset(blocks.dig(:sound, :effective)),
+            badge:,
+          )
+        rescue NotificationTypes::NotFoundError
+          fall_back(reason_code: "type_unregistered")
+        rescue Preferences::StoreError, Preferences::InvalidPreferenceStateError
+          fall_back(reason_code: "preference_unreadable", badge:)
+        end
+
+        private
+
+        # A type the member cannot configure ignores any stored override, as the
+        # channel evaluation does.
+        def stored_state(declaration)
+          return nil unless declaration.user_configurable
+
+          Preferences::Store.find(
+            recipient_id: @communication.user_id,
+            notification_type_key: declaration.key,
+          )
+        end
+
+        def sound_asset(sound_id)
+          SoundCatalog.fetch(sound_id)&.fetch(:asset)
+        end
+
+        # Nil for a type that is not badge-eligible, so the adapter omits Expo `badge`.
+        # The count is NPB-4's absolute eligible unread total, including 0.
+        def badge_count(declaration)
+          return nil unless declaration.badge_eligible
+
+          Inbox.unread_count(recipient_id: @communication.user_id).badge_count
+        end
+
+        def build(urgency:, sound:, badge: nil)
+          Result.new(
+            urgency:,
+            sound:,
+            thread_id: @communication.conversation_key.presence,
+            badge:,
+          ).freeze
+        end
+
+        def fall_back(reason_code:, badge: nil)
+          Execution::OperationLogger.push_presentation_fallback(
+            communication: @communication,
+            reason_code:,
+            channel_delivery: @channel_delivery,
+          )
+          build(urgency: DEFAULT_URGENCY, sound: nil, badge:)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/rendering/rendered_push_payload.rb

@@ -6,14 +6,33 @@ module CommandTower
       # Provider-neutral Expo push rendered payload. recipient_address is the opaque
       # first eligible endpoint id for the ChannelRenderer gate — never the Expo token.
       # Fan-out uses AdapterRequest#eligible_endpoint_ids.
+      #
+      # `sound` is the host sound asset file name, or nil for System Default. `urgency` is
+      # the member's effective urgency level. `thread_id` is the conversation key, or nil
+      # for a standalone message. `badge` is the absolute badge-eligible unread count, or
+      # nil when the type is not badge-eligible. The provider adapter maps them to its
+      # own fields. A badge of 0 is a real count.
       RenderedPushPayload = Data.define(
         :recipient_address,
         :title,
         :body,
         :deep_link,
+        :sound,
+        :urgency,
+        :thread_id,
+        :badge,
       ) do
-        def self.build(recipient_address:, title:, body:, deep_link: nil)
-          values = [recipient_address, title, body, deep_link]
+        def self.build(
+          recipient_address:,
+          title:,
+          body:,
+          deep_link: nil,
+          sound: nil,
+          urgency: "normal",
+          thread_id: nil,
+          badge: nil
+        )
+          values = [recipient_address, title, body, deep_link, sound, urgency, thread_id, badge]
           raise ArgumentError, "arbitrary hashes are not accepted" if values.any? { |v| v.is_a?(Hash) }
           raise ArgumentError, "ActiveRecord objects are not accepted" if values.any? { |v| active_record_like?(v) }
           raise ArgumentError, "raw exception objects are not accepted" if values.any? { |v| v.is_a?(Exception) }
@@ -21,16 +40,22 @@ module CommandTower
           validate_required_string!(recipient_address, "recipient_address")
           validate_required_string!(title, "title")
           validate_required_string!(body, "body")
-          unless deep_link.nil?
-            raise ArgumentError, "deep_link must be a String" unless deep_link.is_a?(String)
-            raise ArgumentError, "deep_link must not be blank when present" if deep_link.strip.empty?
-          end
+          validate_optional_string!(deep_link, "deep_link")
+          validate_optional_string!(sound, "sound")
+          validate_urgency!(urgency)
+          validate_optional_string!(thread_id, "thread_id")
+          validate_badge!(badge)
+          raise ArgumentError, "thread_id must be at most 128 characters" if thread_id && thread_id.length > 128
 
           new(
             recipient_address:,
             title:,
             body:,
             deep_link:,
+            sound:,
+            urgency:,
+            thread_id:,
+            badge:,
           ).freeze
         end
 
@@ -40,6 +65,29 @@ module CommandTower
         end
         private_class_method :validate_required_string!
 
+        def self.validate_optional_string!(value, field_name)
+          return if value.nil?
+
+          raise ArgumentError, "#{field_name} must be a String" unless value.is_a?(String)
+          raise ArgumentError, "#{field_name} must not be blank when present" if value.strip.empty?
+        end
+        private_class_method :validate_optional_string!
+
+        def self.validate_urgency!(urgency)
+          return if NotificationTypes::URGENCY_LEVELS.include?(urgency)
+
+          raise ArgumentError, "urgency must be one of #{NotificationTypes::URGENCY_LEVELS.join(', ')}"
+        end
+        private_class_method :validate_urgency!
+
+        def self.validate_badge!(badge)
+          return if badge.nil?
+          return if badge.is_a?(Integer) && badge >= 0
+
+          raise ArgumentError, "badge must be a nonnegative integer"
+        end
+        private_class_method :validate_badge!
+
         def self.active_record_like?(value)
           defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
         end