command_tower 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b75ad05bfb533351f79dcf7c242e201a225d86cedd0a3f97358a01e91cbb830
-  data.tar.gz: e5e89fe1645e781155862a124f37c625ad0804593959d118d5e8f2c523d629a2
+  metadata.gz: b932782bd089979dc908cc1865cdeefe8839fba2a4e5dbdb4956e00484345450
+  data.tar.gz: c88d647eaa666f9593416acb3771e407f22d2ef090c7035f45b65b4cc2ff9265
 SHA512:
-  metadata.gz: fdbc47eafe86db87598541f3c4cbf86a4b23876e321eb137bef5f2a5d9e9b04f2adfb2d38c822b1980bfd150384443717eab03980442975aa93318fb909e2473
-  data.tar.gz: d374ca61c7fef265974aa71ed8c9bee9c98401efb6328cc240b5685997c8fbf9c1e00928fd2bf2bdd0879e7a013acb0a46200a14133307df57b66da0a44ec391
+  metadata.gz: b3cff84a5ecf68c9929e4c9eca099c2f551a97a886e8c2882b6d4e411d064cb9df24fb64e626b35e08d53b72bcca68950c5e7cd4c197c482415f040e76f89be4
+  data.tar.gz: aaa5bf71dadf4a4a8de13bcc25dd9c826a68c20c37cc014b86130b86d8ad7733d6a575608057a1f19c1d4e2435b79c5a2f679d7f8bb7d73c411886c9dfdfd712

data/app/deserializers/command_tower/deserializers/messaging/preferences/update_deserializer.rb

@@ -8,7 +8,7 @@ module CommandTower
           Input = Data.define(:notification_type_key, :preference_state)
 
           ROUTING_KEYS = %w[controller action format notification_type_key preference].freeze
-          ALLOWED_PREFERENCE_KEYS = %w[inboxEnabled channels].freeze
+          ALLOWED_PREFERENCE_KEYS = %w[inboxEnabled channels urgency sound].freeze
 
           def call(params)
             raw = normalize_hash(params)
@@ -88,6 +88,15 @@ module CommandTower
               state["inbox"] = inbox
             end
 
+            %w[urgency sound].each do |field|
+              next unless preferences.key?(field)
+
+              value = preferences[field]
+              return failure(errors: { message: "invalid_#{field}" }) unless value.is_a?(String) && !value.strip.empty?
+
+              state[field] = value.strip
+            end
+
             state
           end
         end

data/app/errors/command_tower/errors/account/push_test_destination_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PushTestDestinationError < CommandTower::Errors::ApplicationError
+        def code
+          "push_test_destination_unresolved"
+        end
+
+        def message
+          "Push test destination is not configured"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/models/command_tower/messaging/inbox_item.rb

@@ -35,6 +35,12 @@ module CommandTower
         deleted_at.present?
       end
 
+      # NPB-5. Archived rows still open the inbox. Deleted rows do not.
+      # ChannelRenderer and the Expo adapter both use this predicate.
+      def live_for_push?
+        !deleted?
+      end
+
       def unread?
         !viewed? && !archived? && !deleted?
       end

data/app/serializers/command_tower/serializers/messaging/inbox.rb

@@ -73,7 +73,7 @@ module CommandTower
 
         class UnreadCountSerializer
           def self.serialize(payload)
-            { count: payload.fetch(:count) }
+            { count: payload.fetch(:count), badgeCount: payload.fetch(:badge_count) }
           end
         end
 

data/app/serializers/command_tower/serializers/messaging/preferences/notification_serializer.rb

@@ -16,6 +16,8 @@ module CommandTower
               inboxAvailable: notification.inbox_available,
               allowedChannels: notification.allowed_channels,
               availableChannels: notification.available_channels,
+              urgency: notification.urgency,
+              sound: notification.sound,
               preferences: {
                 inboxEnabled: notification.inbox_enabled,
                 channels: notification.channels,

data/app/services/command_tower/messaging/execution/adapter_result.rb

@@ -8,6 +8,7 @@ module CommandTower
         :normalized_provider_status,
         :provider_message_id,
         :error_code,
+        :provider_metadata,
       ) do
         OUTCOMES = %i[success retryable_failure terminal_failure].freeze
 
@@ -15,7 +16,8 @@ module CommandTower
           outcome:,
           normalized_provider_status: nil,
           provider_message_id: nil,
-          error_code: nil
+          error_code: nil,
+          provider_metadata: nil
         )
           raise InvalidAdapterContractError, "arbitrary hashes are not accepted as outcome" if outcome.is_a?(Hash)
           raise InvalidAdapterContractError, "raw exception objects are not accepted" if exception_like?(outcome) ||
@@ -28,12 +30,14 @@ module CommandTower
           validate_optional_string!(normalized_provider_status, "normalized_provider_status")
           validate_optional_string!(provider_message_id, "provider_message_id")
           validate_optional_string!(error_code, "error_code")
+          validate_optional_hash!(provider_metadata, "provider_metadata")
 
           new(
             outcome: normalized_outcome,
             normalized_provider_status:,
             provider_message_id:,
             error_code:,
+            provider_metadata:,
           ).freeze
         end
 
@@ -53,6 +57,12 @@ module CommandTower
         end
         private_class_method :validate_optional_string!
 
+        def self.validate_optional_hash!(value, field_name)
+          return if value.nil?
+          raise InvalidAdapterContractError, "#{field_name} must be a Hash" unless value.is_a?(Hash)
+        end
+        private_class_method :validate_optional_hash!
+
         def self.exception_like?(value)
           value.is_a?(Exception)
         end

data/app/services/command_tower/messaging/execution/adapters/expo/adapter.rb

@@ -17,6 +17,7 @@ module CommandTower
               :receipt,
               :outcome,
               :error_code,
+              :submitted,
               keyword_init: true,
             )
 
@@ -29,6 +30,7 @@ module CommandTower
             def call(request:)
               raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
 
+              attempts = nil
               rendered = request.rendered
               unless rendered.is_a?(Rendering::RenderedPushPayload)
                 return AdapterResult.build(outcome: :terminal_failure, error_code: "render_failed")
@@ -43,25 +45,43 @@ module CommandTower
                 return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
               end
 
-              delivery = Messaging::ChannelDelivery.includes(:communication).find_by(id: request.channel_delivery_id)
+              delivery = Messaging::ChannelDelivery.includes(communication: :inbox_item).find_by(id: request.channel_delivery_id)
               owner_user_id = delivery&.communication&.user_id
               if owner_user_id.nil?
                 return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
               end
 
-              attempts = build_endpoint_attempts(owner_user_id:, endpoint_ids:)
+              history = EndpointTicketHistory.call(
+                channel_delivery_id: delivery.id,
+                excluding_attempt_id: request.attempt_id,
+              )
+              unsettled_ids = endpoint_ids - history.settled_endpoint_ids
+              return settled_only_result(history) if unsettled_ids.empty?
+
+              attempts = build_endpoint_attempts(owner_user_id:, endpoint_ids: unsettled_ids)
               return attempts if attempts.is_a?(AdapterResult)
 
               case @configuration.adapter_name
               when "fake", "log"
                 AdapterResult.build(outcome: :success, normalized_provider_status: "accepted")
               when "http"
-                deliver_http(attempts:, rendered:, owner_user_id:)
+                deliver_http(
+                  attempts:,
+                  rendered:,
+                  owner_user_id:,
+                  history:,
+                  communication: delivery.communication,
+                )
               else
                 AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
               end
             rescue StandardError
-              AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
+              # Keep the endpoint facts already recorded; the outcome stays today's rescue-all result.
+              AdapterResult.build(
+                outcome: :retryable_failure,
+                error_code: "expo_transient",
+                provider_metadata: provider_metadata_for(attempts),
+              )
             end
 
             private
@@ -86,13 +106,14 @@ module CommandTower
               attempts
             end
 
-            def deliver_http(attempts:, rendered:, owner_user_id:)
+            def deliver_http(attempts:, rendered:, owner_user_id:, history:, communication:)
               sendable = attempts.select { |attempt| attempt.token.present? && attempt.outcome.nil? }
-              messages = sendable.map { |attempt| expo_message(token: attempt.token, rendered:) }
+              messages = sendable.map { |attempt| expo_message(token: attempt.token, rendered:, communication:) }
 
+              sendable.each { |attempt| attempt.submitted = true }
               send_result = @http_client.send_messages(messages)
               unless send_result[:ok]
-                return map_http_failure(send_result[:status_code])
+                return map_http_failure(send_result[:status_code], attempts:, history:)
               end
 
               tickets = Array(send_result[:tickets])
@@ -124,19 +145,49 @@ module CommandTower
                 mark_invalid_if_needed!(owner_user_id:, attempt:)
               end
 
-              aggregate_result(attempts)
+              aggregate_result(attempts, history:)
+            end
+
+            # Every eligible endpoint already holds an accepted ticket or a recorded terminal
+            # ticket error from an earlier attempt, so there is nothing to send.
+            def settled_only_result(history)
+              if history.accepted?
+                return AdapterResult.build(
+                  outcome: :success,
+                  normalized_provider_status: "accepted",
+                  provider_message_id: history.first_accepted_ticket_id,
+                )
+              end
+
+              AdapterResult.build(
+                outcome: :terminal_failure,
+                error_code: history.first_terminal_error_code || "expo_rejected",
+              )
             end
 
-            def expo_message(token:, rendered:)
+            def expo_message(token:, rendered:, communication:)
               message = {
                 "to" => token,
                 "title" => rendered.title,
                 "body" => rendered.body,
-                "sound" => "default",
+                "sound" => rendered.sound || "default",
               }
-              if rendered.deep_link.present?
-                message["data"] = { "deepLink" => rendered.deep_link }
+              interruption_level = InterruptionLevel.call(
+                urgency: rendered.urgency,
+                supported: @configuration.supported_interruption_levels,
+              )
+              message["interruptionLevel"] = interruption_level if interruption_level
+              message["threadId"] = rendered.thread_id if rendered.thread_id
+              # nil omits the field. 0 is a real count and must be sent. In Ruby, 0 is truthy.
+              message["badge"] = rendered.badge unless rendered.badge.nil?
+              data = {}
+              data["deepLink"] = rendered.deep_link if rendered.deep_link.present?
+              item = communication&.inbox_item
+              if item&.live_for_push?
+                data["inboxItemId"] = item.id.to_s
+                data["inboxEntryId"] = communication.conversation_key.presence || item.id.to_s
               end
+              message["data"] = data if data.any?
               message
             end
 
@@ -195,31 +246,101 @@ module CommandTower
               nil
             end
 
-            def map_http_failure(status_code)
-              if status_code.to_i >= 500 || status_code.to_i == 429
-                AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
-              else
-                AdapterResult.build(outcome: :terminal_failure, error_code: "expo_rejected")
-              end
+            # 5xx and 429 stay retryable. Any other non-success response is terminal for this
+            # attempt even when an earlier attempt had accepted tickets; those tickets are carried
+            # into the metadata so the accepted facts stay visible on this row.
+            def map_http_failure(status_code, attempts:, history:)
+              retryable = status_code.to_i >= 500 || status_code.to_i == 429
+              outcome = retryable ? :retryable_failure : :terminal_failure
+              error_code = retryable ? "expo_transient" : "expo_rejected"
+              attempts.each { |attempt| attempt.error_code ||= error_code if attempt.submitted }
+              carried = retryable ? [] : carried_accepted_entries(history)
+
+              AdapterResult.build(outcome:, error_code:, provider_metadata: provider_metadata_for(attempts, carried:))
             end
 
-            def aggregate_result(attempts)
+            # Delivery-wide aggregation: this attempt's endpoints plus tickets recorded earlier.
+            def aggregate_result(attempts, history:)
               successes = attempts.select { |attempt| attempt.outcome == :success }
-              if successes.any?
-                first_ticket_id = successes.filter_map { |attempt| attempt.ticket&.dig(:id) }.first
+              first_ticket_id = successes.filter_map { |attempt| attempt.ticket&.dig(:id) }.first
+              metadata = provider_metadata_for(attempts)
+
+              if attempts.any? { |attempt| attempt.outcome == :retryable_failure }
+                return AdapterResult.build(
+                  outcome: :retryable_failure,
+                  error_code: "expo_transient",
+                  provider_message_id: first_ticket_id,
+                  provider_metadata: metadata,
+                )
+              end
+
+              if successes.any? || history.accepted?
                 return AdapterResult.build(
                   outcome: :success,
                   normalized_provider_status: "accepted",
-                  provider_message_id: first_ticket_id,
+                  provider_message_id: first_ticket_id || history.first_accepted_ticket_id,
+                  provider_metadata: metadata,
                 )
               end
 
               if attempts.all? { |attempt| attempt.outcome == :terminal_failure }
-                error_code = attempts.map(&:error_code).compact.first || "expo_rejected"
-                return AdapterResult.build(outcome: :terminal_failure, error_code:)
+                error_code = attempts.filter_map(&:error_code).first ||
+                  history.first_terminal_error_code ||
+                  "expo_rejected"
+                return AdapterResult.build(outcome: :terminal_failure, error_code:, provider_metadata: metadata)
+              end
+
+              AdapterResult.build(
+                outcome: :retryable_failure,
+                error_code: "expo_transient",
+                provider_metadata: metadata,
+              )
+            end
+
+            def carried_accepted_entries(history)
+              history.accepted_ticket_ids.map do |endpoint_id, ticket_id|
+                entry = { "endpoint_id" => endpoint_id, "ticket_status" => "ok" }
+                entry["ticket_id"] = ticket_id if ticket_id.present?
+                entry
               end
+            end
+
+            # Per-device facts as recorded so far. Endpoints never submitted to Expo carry
+            # no ticket or receipt status. No tokens, bodies, or exceptions are included.
+            def provider_metadata_for(attempts, carried: [])
+              return nil unless attempts.is_a?(Array) && attempts.any?(&:submitted)
+
+              { "expo" => { "endpoints" => attempts.map { |attempt| endpoint_metadata(attempt) } + carried } }
+            end
 
-              AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
+            def endpoint_metadata(attempt)
+              entry = { "endpoint_id" => attempt.endpoint_id }
+              if attempt.submitted
+                ticket_id = attempt.ticket&.dig(:id)
+                entry["ticket_id"] = ticket_id if ticket_id.present?
+                entry["ticket_status"] = ticket_status_for(attempt)
+                entry["receipt_status"] = receipt_status_for(attempt)
+              end
+              entry["error_code"] = attempt.error_code if attempt.error_code.present?
+              entry
+            end
+
+            def ticket_status_for(attempt)
+              case attempt.ticket&.dig(:status)
+              when "ok" then "ok"
+              when "error" then "error"
+              else "missing"
+              end
+            end
+
+            def receipt_status_for(attempt)
+              return "unchecked" unless ticket_status_for(attempt) == "ok"
+
+              case attempt.receipt&.dig(:status)
+              when "ok" then "ok"
+              when "error" then "error"
+              else "pending"
+              end
             end
           end
         end

data/app/services/command_tower/messaging/execution/adapters/expo/configuration.rb

@@ -34,6 +34,11 @@ module CommandTower
             def access_token
               CommandTower.config.messaging.expo.access_token.to_s.strip
             end
+
+            # Urgency levels the host's shipped binary can honor. Normal is always supported.
+            def supported_interruption_levels
+              (Array(CommandTower.config.messaging.expo.interruption_levels).map(&:to_s) | ["normal"]).freeze
+            end
           end
         end
       end

data/app/services/command_tower/messaging/execution/adapters/expo/endpoint_ticket_history.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Expo
+          # Read-only lookup over the provider_metadata that earlier attempts of one delivery
+          # recorded: which endpoints already hold an accepted Expo ticket and which hit a
+          # terminal ticket error. Used so a retry only sends to endpoints still unsettled.
+          class EndpointTicketHistory
+            History = Data.define(:accepted_ticket_ids, :terminal_error_codes) do
+              def settled_endpoint_ids
+                accepted_ticket_ids.keys | terminal_error_codes.keys
+              end
+
+              def accepted?
+                accepted_ticket_ids.any?
+              end
+
+              def first_accepted_ticket_id
+                accepted_ticket_ids.values.first
+              end
+
+              def first_terminal_error_code
+                terminal_error_codes.values.first
+              end
+            end
+
+            def self.call(channel_delivery_id:, excluding_attempt_id:)
+              new(channel_delivery_id:, excluding_attempt_id:).call
+            end
+
+            def initialize(channel_delivery_id:, excluding_attempt_id:)
+              @channel_delivery_id = channel_delivery_id
+              @excluding_attempt_id = excluding_attempt_id
+            end
+
+            def call
+              accepted = {}
+              rejected = {}
+
+              recorded_endpoints.each do |entry|
+                endpoint_id = entry["endpoint_id"]
+                next if endpoint_id.nil?
+
+                case entry["ticket_status"]
+                when "ok"
+                  if entry["receipt_status"] == "error"
+                    # Accepted ticket but the receipt reported a failure: terminal for that device.
+                    rejected[endpoint_id] ||= entry["error_code"]
+                  else
+                    accepted[endpoint_id] ||= entry["ticket_id"]
+                  end
+                when "error"
+                  rejected[endpoint_id] ||= entry["error_code"]
+                end
+              end
+
+              History.new(
+                accepted_ticket_ids: accepted.freeze,
+                terminal_error_codes: rejected.except(*accepted.keys).freeze,
+              ).freeze
+            end
+
+            private
+
+            def recorded_endpoints
+              Messaging::DeliveryAttempt
+                .where(channel_delivery_id: @channel_delivery_id)
+                .where.not(id: @excluding_attempt_id)
+                .order(:started_at, :id)
+                .pluck(:provider_metadata)
+                .flat_map { |metadata| endpoints_in(metadata) }
+            end
+
+            def endpoints_in(metadata)
+              endpoints = metadata.is_a?(Hash) ? metadata.dig("expo", "endpoints") : nil
+              endpoints.is_a?(Array) ? endpoints.grep(Hash) : []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/expo/interruption_level.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Expo
+          # Maps a member's neutral urgency to Expo's `interruptionLevel`, degrading to the
+          # highest level the host says its shipped binary can honor:
+          # critical -> time_sensitive -> normal. Normal is the platform default, so it
+          # sends no level. Pure: no I/O.
+          class InterruptionLevel
+            EXPO_LEVELS = {
+              "time_sensitive" => "time-sensitive",
+              "critical" => "critical",
+            }.freeze
+            DEGRADE_ORDER = %w[critical time_sensitive].freeze
+
+            def self.call(urgency:, supported:)
+              new(urgency:, supported:).call
+            end
+
+            def initialize(urgency:, supported:)
+              @urgency = urgency.to_s
+              @supported = Array(supported).map(&:to_s)
+            end
+
+            # The Expo level string, or nil when the message should carry none.
+            def call
+              start = DEGRADE_ORDER.index(@urgency)
+              return nil if start.nil?
+
+              level = DEGRADE_ORDER.drop(start).find { |candidate| @supported.include?(candidate) }
+              EXPO_LEVELS[level]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/attempt_ledger.rb

@@ -55,6 +55,7 @@ module CommandTower
                 finished_at: now,
                 normalized_provider_status: result.normalized_provider_status,
                 provider_message_id: result.provider_message_id,
+                provider_metadata: result.provider_metadata,
                 error_code: nil,
                 error_class: nil,
               )
@@ -65,6 +66,7 @@ module CommandTower
                 finished_at: now,
                 normalized_provider_status: result.normalized_provider_status,
                 provider_message_id: result.provider_message_id,
+                provider_metadata: result.provider_metadata,
                 error_code: result.error_code,
                 error_class: nil,
               )
@@ -75,6 +77,7 @@ module CommandTower
                 finished_at: now,
                 normalized_provider_status: result.normalized_provider_status,
                 provider_message_id: result.provider_message_id,
+                provider_metadata: result.provider_metadata,
                 error_code: result.error_code,
                 error_class: nil,
               )