command_tower 0.15.0 → 0.17.0

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Internal Messaging::Rendering collaborator (peer of `ChannelRenderer`,
+      # not a host-facing service). Builds the `InboxDocument` shown at Inbox
+      # detail read time.
+      #
+      # Generic path: one `paragraph` block from `communication.body`, plus an
+      # optional `cta` block with a typed `destination` — internal
+      # (`metadata["deep_link_path"]`, origin-free, host-navigation-owned) if
+      # present and safe, else external (`metadata["deep_link"]`) if that is
+      # a safe href (D-INBOX-GENERIC; typed destination added Slice 2.6.4).
+      #
+      # Optional per-`notification_type_key` override: a pure-Ruby composer
+      # class (`declaration.inbox_document_composer`, resolved via
+      # `NotificationTypes.lookup` + `.constantize`), `.call(communication:) ->
+      # InboxDocument`. Any failure (unregistered type, absent composer,
+      # unresolvable class name, a raising composer, or a composer returning
+      # something other than an `InboxDocument`) fails open to the generic
+      # document — the Inbox read path must never 500 on a bad type composer
+      # (D-INBOX-TYPE). This replaces the Rich Messaging Campaign 2 ERB/JSON
+      # authoring path entirely — see
+      # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md.
+      #
+      # After the document (type-specific or generic) is built, any
+      # `"presentation"` block is resolved against
+      # `CommandTower.config.registry.inbox_presentations` — at most one
+      # attempted/resolved presentation capability per document (Rich
+      # Messaging Slice 2.5). The budget is consumed the instant a
+      # `"presentation"`-typed block is seen, before lookup or composition,
+      # regardless of outcome, so a malformed/unregistered first node cannot
+      # fail open and then let a second node still execute composer domain
+      # I/O.
+      #
+      # The composer's raw result is always projected down to the
+      # registration's declared `output_keys` before it reaches
+      # `content.blocks[].data` (corrective slice — presentation
+      # ServiceResult/context leak fix). Composer inputs and any other
+      # incidental context/result keys never reach the wire, regardless of
+      # whether the composer is `ApplicationService`-shaped or a plain Hash.
+      class InboxDocumentRenderer
+        UNSAFE_SCHEMES = %w[javascript data vbscript].freeze
+        DEFAULT_CTA_LABEL = "Open"
+
+        def self.render(communication:, recipient_id:)
+          new(communication:, recipient_id:).render
+        end
+
+        def initialize(communication:, recipient_id:)
+          @communication = communication
+          @recipient_id = recipient_id
+          @presentation_attempted = false
+        end
+
+        def render
+          document = build_from_type_composer || build_generic
+
+          resolve_presentation_blocks(document)
+        end
+
+        private
+
+        attr_reader :communication, :recipient_id
+
+        def build_from_type_composer
+          declaration = CommandTower::Messaging::NotificationTypes.lookup(communication.notification_type_key)
+          composer_name = declaration.inbox_document_composer
+          return nil if composer_name.nil?
+
+          document = composer_name.constantize.call(communication:)
+          document.is_a?(InboxDocument) ? document : nil
+        rescue StandardError
+          # Fail-open: unregistered type, unresolvable class name, a raising
+          # composer, or a composer returning invalid data must never surface
+          # as a 500 on the Inbox read path (D-INBOX-TYPE).
+          nil
+        end
+
+        def build_generic
+          blocks = []
+          blocks << paragraph_block(communication.body) if communication.body.present?
+          cta = generic_cta_block
+          blocks << cta if cta
+
+          InboxDocument.build(blocks:)
+        end
+
+        # Re-walks the already-validated blocks array (produced either by a
+        # trusted Ruby composer via `InboxDocument::Builder` or by
+        # `build_generic`), resolving any `"presentation"` node in place.
+        # There is no untrusted JSON to parse/whitelist here — every block was
+        # already constructed via a whitelisted `Builder` method or this
+        # class's own `paragraph_block`/`cta_block` helpers.
+        def resolve_presentation_blocks(document)
+          resolved = document.blocks.map do |block|
+            block[:type] == "presentation" ? presentation_block(block) : block
+          end.compact
+
+          InboxDocument.build(blocks: resolved)
+        end
+
+        def presentation_block(block)
+          return nil if @presentation_attempted
+
+          @presentation_attempted = true
+          key = block[:key]
+          variant = block[:variant]
+
+          definition = CommandTower.config.registry.inbox_presentations.fetch(key)
+          composer_result = definition.composer_class.constantize.call(communication:, recipient_id:)
+
+          # Duck-typed: a registered composer may be a plain class returning a
+          # Hash directly, or a `CommandTower::Services::ApplicationService`
+          # (whose `.call` always returns a `ServiceResult`) — either way the
+          # unwrapped result below is a plain Hash (Rich Messaging Presentation
+          # Authority's composer contract).
+          if composer_result.respond_to?(:success?)
+            return nil unless composer_result.success?
+
+            raw_data = composer_result.data
+          else
+            raw_data = composer_result
+          end
+
+          # Explicit output projection (corrective slice — presentation
+          # ServiceResult/context leak fix): only the keys the presentation's
+          # own registration declares in `output_keys` ever reach
+          # `content.blocks[].data`. This is a declared allow-list owned by
+          # the registration, not an inference from `ApplicationService`
+          # argument metadata — composer inputs (e.g. `communication`,
+          # `recipient_id` on an `ApplicationService`-shaped composer),
+          # incidental intermediate context/result keys, and anything else
+          # are dropped unconditionally here, independent of composer shape.
+          { type: "presentation", key:, variant:, data: raw_data.to_h.slice(*definition.output_keys) }.freeze
+        rescue StandardError
+          # Fail-open: unregistered capability, unresolvable composer class,
+          # or a raising/failing composer must never surface as a 500 on the
+          # Inbox read path, and must never allow a subsequent presentation
+          # block in the same document to still attempt composition (the
+          # budget above is consumed regardless of this outcome).
+          nil
+        end
+
+        def paragraph_block(text)
+          return nil unless text.is_a?(String)
+          return nil if text.empty?
+
+          { type: "paragraph", text: }.freeze
+        end
+
+        def generic_cta_block
+          cta_block(
+            label: metadata_value("cta_label"),
+            path: metadata_value("deep_link_path"),
+            href: metadata_value("deep_link")
+          )
+        end
+
+        # Internal (`path`) takes precedence over external (`href`) when
+        # both are present — a `cta` only ever means one navigation intent
+        # (Slice 2.6.4 typed destination; see artifacts/visual-improvements/
+        # rich-messaging/plans/2.6.4-ct-fe-inbox-navigation-capability.md).
+        def cta_block(label:, path: nil, href: nil)
+          destination = cta_destination(path:, href:)
+          return nil unless destination
+
+          resolved_label = label.is_a?(String) && !label.strip.empty? ? label : DEFAULT_CTA_LABEL
+          { type: "cta", label: resolved_label, destination: }.freeze
+        end
+
+        def cta_destination(path:, href:)
+          if safe_internal_path?(path)
+            { kind: "internal", path: }
+          elsif safe_href?(href)
+            { kind: "external", href: }
+          end
+        end
+
+        # A leading `//` is rejected even though it "starts with a slash" —
+        # it is a protocol-relative URL, not a safe same-app-only destination.
+        def safe_internal_path?(path)
+          path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
+        end
+
+        def safe_href?(href)
+          return false unless href.is_a?(String) && !href.strip.empty?
+
+          scheme = URI.parse(href).scheme&.downcase
+          scheme.present? && UNSAFE_SCHEMES.exclude?(scheme)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def metadata_value(key)
+          metadata = communication.metadata
+          return nil unless metadata.is_a?(Hash)
+
+          metadata[key] || metadata[key.to_sym]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "action_view"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Internal Execution-pipeline collaborator (not a Service/Workflow/Controller).
+      #
+      # Resolves one rendered-destination basename (e.g. "email", "sms") to an
+      # ActionView template, preferring a `notification_type_key`-specific view
+      # over the generic one, and preferring the host application's `app/views`
+      # over CommandTower's own engine views for either.
+      #
+      # Host convention (documentation, not code):
+      #
+      #   app/views/command_tower/messaging/rendering/
+      #     email.html.erb                     # optional host override of the generic chrome
+      #     <notification_type_key>/email.html.erb  # optional type-specific override
+      #
+      # Hosts customize by dropping ERB files at that path; they never call this
+      # class directly. `ChannelRenderer` remains the only public Ruby entry into
+      # rendering. `prepend_view_path`/`reset_view_paths!` exist solely as a
+      # messaging spec fixture seam (mirrors Rails' own `prepend_view_path`
+      # testing idiom) and are not part of any host-facing contract.
+      class TemplateResolver
+        TEMPLATE_PREFIX = "command_tower/messaging/rendering"
+        TYPE_KEY_PATTERN = /\A[a-z0-9_]+\z/
+
+        class << self
+          def render(basename:, format:, notification_type_key:, generic_locals:, type_locals:)
+            new.render(
+              basename:,
+              format:,
+              notification_type_key:,
+              generic_locals:,
+              type_locals:,
+            )
+          end
+
+          # Spec-only seam: prepend an additional view root ahead of the host
+          # and engine defaults so fixture views can prove override precedence.
+          def prepend_view_path(path)
+            extra_view_paths.unshift(path.to_s)
+          end
+
+          def reset_view_paths!
+            extra_view_paths.clear
+          end
+
+          # Type-only, no-generic-fallback resolution: returns `nil` when
+          # there is no matching type template (invalid/sanitized-out key, or
+          # the type directory/basename simply does not exist) instead of
+          # raising `Errno::ENOENT` like `.render` does. Callers that have no
+          # generic ERB file to fall back to (e.g. `InboxDocumentRenderer`,
+          # whose generic path is a pure-Ruby builder) use this instead of
+          # `.render`. A template that is *found* but raises mid-render still
+          # propagates (via `render_named`'s `ActionView::Template::Error`
+          # unwrap) so callers can distinguish "no type content" from "type
+          # content is broken" if they choose to.
+          def render_type_template(basename:, format:, notification_type_key:, locals:)
+            new.render_type_template(basename:, format:, notification_type_key:, locals:)
+          end
+
+          def extra_view_paths
+            @extra_view_paths ||= []
+          end
+        end
+
+        def render(basename:, format:, notification_type_key:, generic_locals:, type_locals:)
+          type_key = sanitized_type_key(notification_type_key)
+
+          if type_key
+            begin
+              return render_named("#{TEMPLATE_PREFIX}/#{type_key}/#{basename}", format, type_locals)
+            rescue ActionView::MissingTemplate
+              # No type-specific template for this basename; fall through to generic.
+            end
+          end
+
+          begin
+            render_named("#{TEMPLATE_PREFIX}/#{basename}", format, generic_locals)
+          rescue ActionView::MissingTemplate
+            raise Errno::ENOENT, "missing template #{basename}.#{format}.erb"
+          end
+        end
+
+        def render_type_template(basename:, format:, notification_type_key:, locals:)
+          type_key = sanitized_type_key(notification_type_key)
+          return nil unless type_key
+
+          render_named("#{TEMPLATE_PREFIX}/#{type_key}/#{basename}", format, locals)
+        rescue ActionView::MissingTemplate
+          nil
+        end
+
+        private
+
+        def sanitized_type_key(notification_type_key)
+          key = notification_type_key.to_s
+          key.match?(TYPE_KEY_PATTERN) ? key : nil
+        end
+
+        def render_named(template_name, format, locals)
+          view.render(template: template_name, formats: [format], locals:)
+        rescue ActionView::Template::Error => error
+          # ActionView wraps any error raised while executing a *found*
+          # template in `ActionView::Template::Error`. Legacy plain-ERB
+          # rendering never wrapped errors, so unwrap here to preserve the
+          # original `error_class` that `ChannelRenderer#render`'s outer
+          # rescue surfaces on `RenderError`.
+          raise(error.cause || error)
+        end
+
+        def view
+          @view ||= ActionView::Base.with_empty_template_cache.with_view_paths(view_paths)
+        end
+
+        def view_paths
+          self.class.extra_view_paths + [
+            Rails.root.join("app/views").to_s,
+            CommandTower::Engine.root.join("app/views").to_s,
+          ]
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/complete.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class Complete < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :experience_key, is_a: String, required: true
+          validate :scope_type, is_a: String, required: true
+          validate :scope_identifier, is_a: String, required: true
+          validate :version, is_a: String, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            identity = {
+              user:,
+              host_key:,
+              experience_key:,
+              scope_type:,
+              scope_identifier:,
+              version:,
+            }
+
+            existing = CommandTower::UserExperienceState.find_by(identity)
+            if existing
+              context.experience_state = existing
+              context.created = false
+              return
+            end
+
+            begin
+              created = CommandTower::UserExperienceState.create!(
+                identity.merge(completed_at: Time.current),
+              )
+              context.experience_state = created
+              context.created = true
+            rescue ActiveRecord::RecordNotUnique
+              recovered = CommandTower::UserExperienceState.find_by!(identity)
+              context.experience_state = recovered
+              context.created = false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class List < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            context.experience_states = CommandTower::UserExperienceState.for_user_and_host(
+              user:,
+              host_key:,
+            ).order(:completed_at, :id).to_a
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/client_compatibility/evaluate.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module ClientCompatibility
+      # Pure, deterministic client-version-compatibility decision.
+      #
+      # Same (headers, controller/action, registry state) always produces the
+      # same complete `Decision`. This service MUST NOT mutate
+      # `CommandTower::Current` or any other request-global — it has zero side
+      # effects beyond returning its result. Any placement of recommendation
+      # metadata onto `Current` is transport plumbing that belongs to the
+      # workflow or boundary layer, never here.
+      class Evaluate
+        DECISIONS = %i[compatible recommended incompatible identity_invalid].freeze
+
+        # Immutable decision/projection. `recommendation_projection` is the
+        # camelCase `clientCompatibility` shape (authority §13), present only
+        # when identity is parseable and current >= effective minimum.
+        class Decision
+          attr_reader :decision, :platform, :current_version, :effective_minimum, :scope,
+                      :recovery, :update_url, :matched_entity_names, :recommendation_projection
+
+          def initialize(
+            decision:,
+            platform: nil,
+            current_version: nil,
+            effective_minimum: nil,
+            scope: nil,
+            recovery: nil,
+            update_url: nil,
+            matched_entity_names: [],
+            recommendation_projection: nil
+          )
+            @decision = decision
+            @platform = platform
+            @current_version = current_version
+            @effective_minimum = effective_minimum
+            @scope = scope
+            @recovery = recovery
+            @update_url = update_url
+            @matched_entity_names = matched_entity_names
+            @recommendation_projection = recommendation_projection
+          end
+
+          def compatible? = %i[compatible recommended].include?(@decision)
+
+          def incompatible? = !compatible?
+        end
+
+        def self.call(app_version_header:, platform_header:, controller_class:, action_name:, registry: CommandTower.config.registry.client_compatibility)
+          new(
+            app_version_header:,
+            platform_header:,
+            controller_class:,
+            action_name:,
+            registry:
+          ).call
+        end
+
+        def initialize(app_version_header:, platform_header:, controller_class:, action_name:, registry:)
+          @app_version_header = app_version_header
+          @platform_header = platform_header
+          @controller_class = controller_class
+          @action_name = action_name.to_s
+          @registry = registry
+        end
+
+        def call
+          return no_op_decision unless registry.opted_in?
+
+          platform = normalized_platform
+          version = normalized_version
+          return identity_invalid_decision(platform:) if platform.nil? || version.nil?
+
+          policy = registry.platform_policy(platform)
+          return identity_invalid_decision(platform:, current_version: version) if policy.nil?
+
+          matched = matched_entity_names
+          effective_minimum, scope = effective_minimum_and_scope(policy:, platform:, matched:)
+
+          current = Gem::Version.new(version)
+          minimum = Gem::Version.new(effective_minimum)
+
+          if current < minimum
+            return incompatible_decision(
+              platform:, current_version: version, effective_minimum:, scope:, matched:, policy:
+            )
+          end
+
+          compatible_or_recommended_decision(
+            platform:, current_version: version, effective_minimum:, matched:, policy:, current:
+          )
+        end
+
+        private
+
+        attr_reader :controller_class, :action_name, :registry
+
+        def normalized_platform
+          token = @platform_header.to_s.strip.downcase
+          return nil if token.empty?
+          return nil unless CommandTower::Configuration::Registry::ClientCompatibility::Config::PLATFORMS.map(&:to_s).include?(token)
+
+          token.to_sym
+        end
+
+        def normalized_version
+          CommandTower::ClientCompatibility::Version.normalize(@app_version_header)
+        end
+
+        def matched_entity_names
+          CommandTower::Authorization::Entity.entities.values
+            .select { |entity| entity.matches?(controller: controller_class, method: action_name.to_sym) == true }
+            .map { |entity| entity.name.to_s }
+        end
+
+        def effective_minimum_and_scope(policy:, platform:, matched:)
+          strictest = policy.minimum
+          scope = :application
+
+          matched.each do |entity_name|
+            requirement = registry.entity_requirement(entity_name)
+            next if requirement.nil?
+
+            entity_minimum = entity_minimum_for(requirement, platform:)
+            next if entity_minimum.nil?
+
+            if Gem::Version.new(entity_minimum) > Gem::Version.new(strictest)
+              strictest = entity_minimum
+              scope = :capability
+            end
+          end
+
+          [strictest, scope]
+        end
+
+        def entity_minimum_for(requirement, platform:)
+          if requirement.client_contract.present?
+            binding = registry.binding_for(requirement.client_contract)
+            binding&.for_platform(platform)
+          else
+            requirement.minimum.for_platform(platform)
+          end
+        end
+
+        def no_op_decision
+          Decision.new(decision: :compatible)
+        end
+
+        def identity_invalid_decision(platform: nil, current_version: nil)
+          Decision.new(
+            decision: :identity_invalid,
+            platform:,
+            current_version:,
+            scope: :application,
+            recovery: recovery_for(platform),
+            update_url: update_url_for(platform)
+          )
+        end
+
+        def incompatible_decision(platform:, current_version:, effective_minimum:, scope:, matched:, policy:)
+          Decision.new(
+            decision: :incompatible,
+            platform:,
+            current_version:,
+            effective_minimum:,
+            scope:,
+            recovery: recovery_for(platform),
+            update_url: update_url_for(platform),
+            matched_entity_names: matched,
+            recommendation_projection: nil
+          )
+        end
+
+        def compatible_or_recommended_decision(platform:, current_version:, effective_minimum:, matched:, policy:, current:)
+          recommended = policy.recommended
+          update_available = recommended.present? && current < Gem::Version.new(recommended)
+
+          Decision.new(
+            decision: update_available ? :recommended : :compatible,
+            platform:,
+            current_version:,
+            effective_minimum:,
+            scope: :application,
+            matched_entity_names: matched,
+            recommendation_projection: recommendation_projection(
+              platform:, current_version:, effective_minimum:, recommended:, update_available:
+            )
+          )
+        end
+
+        def recommendation_projection(platform:, current_version:, effective_minimum:, recommended:, update_available:)
+          {
+            platform: platform.to_s,
+            currentVersion: current_version,
+            minimumVersion: effective_minimum,
+            recommendedVersion: recommended,
+            updateAvailable: update_available,
+            recovery: recovery_for(platform).to_s,
+            updateUrl: update_url_for(platform)
+          }.compact
+        end
+
+        def recovery_for(platform)
+          return :reload if platform.nil? || platform == :web
+
+          :app_store
+        end
+
+        def update_url_for(platform)
+          return nil if platform.nil? || platform == :web
+
+          registry.platform_policy(platform)&.update_url
+        end
+      end
+    end
+  end
+end

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

@@ -120,7 +120,14 @@ module CommandTower
             communication = CommandTower::Messaging::Contract::Communications.find(
               CommandTower::Messaging::Contract::Requests::FindCommunication.build(communication_id: item.communication_id, recipient_id:)
             )
-            item(item).merge(body: communication.body, metadata: communication.metadata, notification_type_key: communication.notification_type_key)
+            content = CommandTower::Messaging::Rendering::InboxDocumentRenderer.render(communication:, recipient_id:).to_h
+
+            item(item).merge(
+              body: communication.body,
+              metadata: communication.metadata,
+              notification_type_key: communication.notification_type_key,
+              content:,
+            )
           end
         end
       end