command_tower 0.3.1 → 0.10.0

data/app/serializers/command_tower/serializers/me/pushover_serializer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      class PushoverSerializer
+        def self.serialize(safe_view)
+          new(safe_view).serialize
+        end
+
+        def self.unconfigured
+          {
+            configured: false,
+            actions: {
+              canCreate: true,
+              canVerify: false,
+              canReplace: false,
+              canRemove: false
+            }
+          }
+        end
+
+        def initialize(safe_view)
+          @safe_view = safe_view
+        end
+
+        def serialize
+          return self.class.unconfigured if @safe_view.nil?
+
+          {
+            configured: true,
+            id: @safe_view.id,
+            channelKey: @safe_view.channel_key,
+            lifecycleState: @safe_view.lifecycle_state,
+            verificationState: @safe_view.verification_state,
+            maskedDisplayValue: @safe_view.masked_display_value,
+            credentialsConfigured: !!@safe_view.credentials_configured,
+            verifiedAt: @safe_view.verified_at&.iso8601,
+            createdAt: @safe_view.created_at&.iso8601,
+            updatedAt: @safe_view.updated_at&.iso8601,
+            actions: actions_for(@safe_view)
+          }
+        end
+
+        private
+
+        def actions_for(view)
+          active = view.lifecycle_state.to_s == "active"
+          {
+            canCreate: false,
+            canVerify: active,
+            canReplace: active,
+            canRemove: active
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Messaging
+      module Inbox
+        class ItemSerializer
+          def self.serialize(item)
+            { id: item.fetch(:id), title: item.fetch(:title), status: item.fetch(:status),
+              read: item[:viewed_at].present?, viewedAt: item[:viewed_at]&.iso8601,
+              createdAt: item[:created_at]&.iso8601, updatedAt: item[:updated_at]&.iso8601 }
+          end
+        end
+
+        class DetailSerializer
+          def self.serialize(item)
+            ItemSerializer.serialize(item).merge(
+              body: item.fetch(:body), metadata: item[:metadata],
+              notificationTypeKey: item.fetch(:notification_type_key)
+            )
+          end
+        end
+
+        class BulkResultSerializer
+          def self.serialize(result)
+            { ids: result.fetch(:ids), count: result.fetch(:count), changedCount: result.fetch(:changed_count) }
+          end
+        end
+
+        class UnreadCountSerializer
+          def self.serialize(payload)
+            { count: payload.fetch(:count) }
+          end
+        end
+
+        class PaginationMetaSerializer
+          def self.serialize(pagination)
+            { limit: pagination.fetch(:limit), offset: pagination.fetch(:offset),
+              totalCount: pagination.fetch(:total_count) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Messaging
+      module Preferences
+        class CatalogSerializer
+          def self.serialize(catalog)
+            {
+              categories: catalog.categories.map { |category| CategorySerializer.serialize(category) },
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Messaging
+      module Preferences
+        class CategorySerializer
+          def self.serialize(category)
+            {
+              key: category.key,
+              label: category.label,
+              description: category.description,
+              order: category.order,
+              notifications: category.notifications.map { |notification|
+                NotificationSerializer.serialize(notification)
+              },
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Messaging
+      module Preferences
+        class NotificationSerializer
+          def self.serialize(notification)
+            {
+              key: notification.key,
+              label: notification.label,
+              description: notification.description,
+              order: notification.order,
+              configurable: notification.configurable,
+              mandatory: notification.mandatory,
+              inboxAvailable: notification.inbox_available,
+              allowedChannels: notification.allowed_channels,
+              availableChannels: notification.available_channels,
+              preferences: {
+                inboxEnabled: notification.inbox_enabled,
+                channels: notification.channels,
+                storedOverridePresent: notification.stored_override_present,
+              },
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/profile/profile_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Profile
+      class ProfileSerializer
+        def self.serialize(user)
+          CommandTower::Serializers::Auth::UserSerializer.serialize(user)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/README.md

@@ -1,12 +1,24 @@
-# CommandTower Service
+# CommandTower ServiceBase
 
-`CommandTower::ServiceBase` an abstraction around the Ruby Gem Interactor. It dds custom functionality to the base Service and is intended to be an inherited Class to create Application logic code. All Services in `CommandTower` utilize this base Service class for convenience and DRYness.
+`CommandTower::ServiceBase` is an abstraction around the Ruby gem Interactor. It adds logging and argument validation on top of Interactor and is the inherited base for **service** classes that implement one business capability.
+
+Services sit **under** workflows in the platform layer map:
+
+```text
+Controller / Job → Workflow → Shared Sequences / Services → Models & Clients
+```
+
+Workflows own orchestration of a business action. Services own how a single capability is performed. Do not treat ServiceBase as the application orchestrator — that is the workflow layer.
+
+Long-form architecture rationale: `artifacts/rails_architecture_handbook.md` (workspace). Condensed enforcement: `.cursor/rules/rails-architecture.mdc` and `.cursor/rules/services.mdc`.
+
+All services in CommandTower that use this pattern inherit `CommandTower::ServiceBase` for consistency.
 
 ## What does ServiceBase offer
 
 ### Logging
 `ServiceBase` offers a convenient way to tag logs. It keeps track of:
-- The start of the the Logic call
+- The start of the logic call
 - The time it took to complete the logic
 - The status of the logic
 
@@ -39,11 +51,15 @@ Other more complex Argument validation includes:
 - Delegate context variable to the class for simplicity
 - Validating Argument length or size is `<` `≤` `==` `>` `≥`
 
-For More information, Check out the [ArgumentValidation ReadMe](argument_validation/README.md)
+For more information, see the [ArgumentValidation ReadMe](argument_validation/README.md)
 
 
-## Basic Examples:
-Check out the examples used in this directory!
+## Examples in the gem
 
+There is no separate examples directory under this path. Real service classes live under capability namespaces, for example:
 
+- `CommandTower::Services::Messaging::Communications::Produce`
+- `CommandTower::Services::Messaging::Communications::ProduceMany`
+- `CommandTower::Services::Me::ChangePassword`
 
+See [Messaging](../../../docs/messaging_integration_guide.md) and [Extending](../../../docs/extending.md).

data/app/services/command_tower/auth/request_context.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    # Transport handle passed from a controller boundary into authentication.
+    # Keeps the request/response pair together so services never reach for
+    # controller state directly. Not a workflow type.
+    class RequestContext
+      attr_reader :request, :response
+
+      def self.from(request, response)
+        new(request:, response:)
+      end
+
+      def initialize(request:, response:)
+        @request = request
+        @response = response
+      end
+    end
+  end
+end

data/app/services/command_tower/authorize/validate.rb

@@ -1,43 +1,79 @@
 # frozen_string_literal: true
 
 module CommandTower::Authorize
-  class Validate < CommandTower::ServiceBase
-    on_argument_validation :fail_early
+  # RBAC decision for a controller action. Shared by the engine's
+  # `authorize_user!` transport filter and the modern AuthorizeRequest service,
+  # so it stays a plain domain object with a narrow decision contract.
+  class Validate
+    include CommandTower::ServiceLogging
 
-    validate :user, is_a: User, required: true
-    validate :controller, is_a: [ActionController::Base, ActionController::API], required: true
-    validate :method, is_a: String, required: true
+    NOT_REQUIRED_MSG = "Authorization not required at this time"
+    AUTHORIZED_MSG = "User is Authorized for action"
+    UNAUTHORIZED_MSG = "Unauthorized Access. Incorrect User Privileges"
+
+    class Decision
+      attr_reader :user, :authorization_required, :msg
+
+      def self.authorized(user:, authorization_required:, msg:)
+        new(success: true, user:, authorization_required:, msg:)
+      end
+
+      def self.denied(user:, msg:)
+        new(success: false, user:, authorization_required: true, msg:)
+      end
+
+      def initialize(success:, user:, authorization_required:, msg:)
+        @success = success
+        @user = user
+        @authorization_required = authorization_required
+        @msg = msg
+      end
+
+      def success? = @success
+
+      def failure? = !@success
+    end
+
+    def self.call(user:, controller:, method:)
+      new(user:, controller:, method:).call
+    end
+
+    def initialize(user:, controller:, method:)
+      @user = user
+      @controller = controller
+      @action = method
+    end
 
     def call
-      context.authorization_required = authorization_required?
-      unless context.authorization_required
-        log_info("controller:#{controller}; method:#{method} -- No Authorization required")
-        context.msg = "Authorization not required at this time"
-        return
+      unless authorization_required?
+        log_info("controller:#{controller}; method:#{action} -- No Authorization required")
+        return Decision.authorized(user:, authorization_required: false, msg: NOT_REQUIRED_MSG)
       end
 
       # At this point we know authorization on the route is required
       # Iterate through the users roles to find a matching role that allows authorization
       # If at least 1 of the users roles passes validation, we can allow access to the path
       log_info("User Roles: #{user.roles}")
-      auhorization_result = user_role_objects.any? do |_role_name, role_object|
-        result = role_object.authorized?(controller:, method:, user:)
+      authorized = user_role_objects.any? do |_role_name, role_object|
+        result = role_object.authorized?(controller:, method: action, user:)
         log_info("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
         result[:authorized] == true
       end
 
-      if auhorization_result
-        context.msg = "User is Authorized for action"
-      else
-        context.fail!(msg: "Unauthorized Access. Incorrect User Privileges")
-      end
+      return Decision.denied(user:, msg: UNAUTHORIZED_MSG) unless authorized
+
+      Decision.authorized(user:, authorization_required: true, msg: AUTHORIZED_MSG)
     end
 
+    private
+
+    attr_reader :user, :controller, :action
+
     def authorization_required?
       controller_mapping = CommandTower::Authorization.mapped_controllers[controller]
       return false if controller_mapping.nil?
 
-      controller_mapping.include?(method.to_sym)
+      controller_mapping.include?(action.to_sym)
     end
 
     def user_role_objects

data/app/services/command_tower/clients/client_base.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    class ClientBase
+      class << self
+        # Internal: resolve a provider class under +root+ via Zeitwerk const_get.
+        # Host product entry extends Invocation so +root+ is the host Clients module.
+        # Not the locked product invocation API.
+        def resolve_provider!(name, root: Clients)
+          const_name = ConstResolution.normalize_name(name)
+          path = "#{root.name}::#{const_name}"
+          klass = ConstResolution.const_get!(root, const_name, expected: "provider")
+
+          unless klass.is_a?(Class) && klass < ClientBase
+            raise Errors::DiscoveryError,
+                  "invalid provider inheritance: expected #{path} < #{ClientBase.name}"
+          end
+
+          klass
+        end
+      end
+
+      def initialize(transport: Transport::FaradayAdapter.new(config: Transport::FaradayConfig.from_env))
+        raise Errors::ConfigurationError, "transport is required" if transport.nil?
+
+        @transport = transport
+        @namespace_mutex = Mutex.new
+        @namespaces = {}
+      end
+
+      # Internal: resolve a namespace module under this provider and wrap NamespaceProxy.
+      # Not the locked product invocation API.
+      def resolve_namespace!(name)
+        const_name = ConstResolution.normalize_name(name)
+
+        @namespace_mutex.synchronize do
+          @namespaces[const_name] ||= build_namespace_proxy!(const_name)
+        end
+      end
+
+      # Primary execution contract.
+      # Accepts a normalized Clients::Transport::Request.
+      # Optional +context:+ is internal framework plumbing (typically ScopedClient).
+      def execute(request, context: nil)
+        validate_request!(request)
+
+        prepared = prepare_request(request, context: context)
+        started_at = monotonic_now
+
+        response = call_transport(prepared, started_at)
+        return response if response.is_a?(ClientResult)
+
+        build_result(response, started_at)
+      end
+
+    # Provider-owned authentication check. Default is a no-op so bare/test
+    # providers keep working; ScopedClient delegates opaque scope kwargs.
+    def enforce_authentication!(**)
+      nil
+    end
+
+      # Strip the transport wrapper before resource deserializers run.
+      # Default payload is the raw body — providers own encoding (JSON, XML, …).
+      def decode_response(response)
+        DecodedResponse.new(
+          payload: response.body,
+          provider_metadata: {}
+        )
+      end
+
+      protected
+
+      # Provider host root (and optional path prefix). Required only when the
+      # request URL is relative. Absolute request URLs are preserved as-is.
+      def base_url
+        nil
+      end
+
+      def default_headers
+        {}
+      end
+
+      def apply_authentication(request, context: nil)
+        request
+      end
+
+      def map_provider_error(response)
+        Errors::UpstreamError.new(
+          message: "Upstream request failed with status #{response.status}",
+          details: { status: response.status }
+        )
+      end
+
+      private
+
+      def build_namespace_proxy!(const_name)
+        path = "#{self.class.name}::#{const_name}"
+        mod = ConstResolution.const_get!(self.class, const_name, expected: "namespace")
+
+        unless mod.instance_of?(Module)
+          raise Errors::DiscoveryError,
+                "invalid namespace: expected #{path} to be a Module (Zeitwerk folder)"
+        end
+
+        NamespaceProxy.new(client: self, namespace_module: mod)
+      end
+
+      def validate_request!(request)
+        return if request.is_a?(Transport::Request)
+
+        raise Errors::ConfigurationError,
+              "request must be a #{Transport::Request.name}"
+      end
+
+      def prepare_request(request, context: nil)
+        with_defaults = Transport::Request.build(
+          method: request.method,
+          url: absolutize_url(request.url),
+          headers: default_headers.merge(request.headers),
+          body: request.body,
+          query: request.query,
+          timeout: request.timeout
+        )
+        apply_authentication(with_defaults, context: context)
+      end
+
+      def absolutize_url(url)
+        return url.to_s if Url.absolute?(url)
+
+        Url.join(base_url, url)
+      end
+
+      def call_transport(prepared, started_at)
+        response = @transport.call(prepared)
+        unless response.is_a?(Transport::Response)
+          raise Errors::ConfigurationError,
+                "transport must return a #{Transport::Response.name}"
+        end
+        response
+      rescue Transport::Error => e
+        ClientResult.failure(
+          error: Errors::UpstreamError.new(message: e.message, cause: e),
+          metadata: natural_metadata(status: nil, started_at: started_at, response: nil)
+        )
+      end
+
+      def build_result(response, started_at)
+        metadata = natural_metadata(
+          status: response.status,
+          started_at: started_at,
+          response: response
+        )
+
+        if response.success?
+          ClientResult.success(output: response, metadata: metadata)
+        else
+          ClientResult.failure(
+            error: map_provider_error(response),
+            output: response,
+            metadata: metadata
+          )
+        end
+      end
+
+      def natural_metadata(status:, started_at:, response:)
+        metadata = {}
+        metadata[:status] = status unless status.nil?
+        duration_ms = response&.duration_ms || elapsed_ms(started_at)
+        metadata[:duration_ms] = duration_ms unless duration_ms.nil?
+        metadata
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed_ms(started_at)
+        ((monotonic_now - started_at) * 1000).round
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/client_result.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    class ClientResult
+      attr_reader :output, :error, :metadata, :provider_metadata
+
+      def initialize(success:, output:, error:, metadata:, provider_metadata: {})
+        @success = success
+        @output = output
+        @error = error
+        @metadata = metadata
+        @provider_metadata = provider_metadata
+      end
+
+      def success?
+        @success
+      end
+
+      def failure?
+        !success?
+      end
+
+      def self.success(output:, metadata: {}, provider_metadata: {})
+        new(
+          success: true,
+          output: output,
+          error: nil,
+          metadata: metadata,
+          provider_metadata: provider_metadata
+        )
+      end
+
+      def self.failure(error:, output: nil, metadata: {}, provider_metadata: {})
+        new(
+          success: false,
+          output: output,
+          error: error,
+          metadata: metadata,
+          provider_metadata: provider_metadata
+        )
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/const_resolution.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Internal constant helpers for provider/namespace/endpoint resolution.
+    # Not a public product API — used by ClientBase / NamespaceProxy and tests.
+    module ConstResolution
+      module_function
+
+      def normalize_name(name)
+        raw = name.to_s.strip
+        if raw.empty?
+          raise Errors::DiscoveryError, "discovery name must be present"
+        end
+
+        raw.camelize
+      end
+
+      def const_get!(parent, name, expected:)
+        const_name = normalize_name(name)
+        path = "#{parent.name}::#{const_name}"
+
+        begin
+          parent.const_get(const_name, false)
+        rescue NameError
+          raise Errors::DiscoveryError,
+                "missing #{expected}: expected #{path}"
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/clients/decoded_response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Clients
+    # Internal handoff from provider decode_response → EndpointBase resource deserializer.
+    # Not a public product wrapper; not placed on ClientResult#output.
+    class DecodedResponse
+      attr_reader :payload, :provider_metadata
+
+      def initialize(payload:, provider_metadata: {})
+        @payload = payload
+        @provider_metadata = provider_metadata
+      end
+    end
+  end
+end