command_tower 0.4.0 → 0.11.0

data/app/serializers/command_tower/serializers/auth/password_recovery_session_response_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class PasswordRecoverySessionResponseSerializer
+        def self.serialize(token:, expires_at:)
+          {
+            recoverySessionToken: token,
+            expiresAt: expires_at.iso8601
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/password_reset/message_response_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      module PasswordReset
+        class MessageResponseSerializer
+          def self.serialize(message:)
+            { message: message }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/password_reset/validate_response_serializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      module PasswordReset
+        class ValidateResponseSerializer
+          def self.serialize(valid:, expires_at:)
+            payload = { valid: valid }
+
+            if expires_at.present?
+              expires_at_value = expires_at.is_a?(Time) || expires_at.is_a?(DateTime) ? expires_at.iso8601 : expires_at.to_s
+              payload[:expiresAt] = expires_at_value
+            end
+
+            payload
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/principal_capabilities_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class PrincipalCapabilitiesSerializer
+        def self.serialize(principal_capability_ids)
+          {
+            principalCapabilities: Array(principal_capability_ids).map(&:to_s)
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/register_response_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class RegisterResponseSerializer
+        def self.serialize(user:)
+          {
+            user: UserSerializer.serialize(user),
+            message: "Account created successfully"
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/session_response_serializer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class SessionResponseSerializer
+        def self.serialize(user:, token_expires_at:, impersonation_session: nil, actor: nil)
+          payload = {
+            user: CommandTower::Serializers::Auth::UserSerializer.serialize(user),
+            tokenExpiresAt: token_expires_at
+          }
+          return payload if impersonation_session.nil?
+
+          actor_user = actor || impersonation_session.actor
+          payload[:impersonation] = {
+            active: true,
+            sessionId: impersonation_session.id,
+            actorUserId: impersonation_session.actor_user_id,
+            actorDisplayName: display_name(actor_user),
+            targetUserId: impersonation_session.target_user_id,
+            idleExpiresAt: CommandTower::Serializers::ApplicationSerializer.iso8601(
+              impersonation_session.idle_expires_at
+            ),
+            absoluteExpiresAt: CommandTower::Serializers::ApplicationSerializer.iso8601(
+              impersonation_session.absolute_expires_at
+            )
+          }
+          payload
+        end
+
+        def self.display_name(user)
+          return nil if user.nil?
+
+          [user.first_name, user.last_name].compact_blank.join(" ").presence || user.username
+        end
+        private_class_method :display_name
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/signup_session_response_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class SignupSessionResponseSerializer
+        def self.serialize(token:, expires_at:)
+          {
+            signupSessionToken: token,
+            expiresAt: expires_at.iso8601
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/user_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class UserSerializer
+        def self.serialize(user)
+          {
+            id: user.id,
+            email: user.email,
+            username: user.username,
+            firstName: user.first_name,
+            lastName: user.last_name,
+            emailValidated: user.email_validated,
+            roles: user.roles
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/username_availability_serializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class UsernameAvailabilitySerializer
+        def self.serialize(valid:, available:, message:)
+          {
+            valid: valid,
+            available: available,
+            message: message
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/impersonation/session_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Impersonation
+      class SessionSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(session)
+          {
+            id: session.id,
+            actorUserId: session.actor_user_id,
+            targetUserId: session.target_user_id,
+            idleExpiresAt: iso8601(session.idle_expires_at),
+            absoluteExpiresAt: iso8601(session.absolute_expires_at)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      class AccountSerializer
+        def self.serialize(user, capabilities:)
+          first_name = user.first_name.to_s
+          last_name = user.last_name.to_s
+          full_name = [first_name, last_name].map(&:strip).reject(&:empty?).join(" ")
+          full_name = user.full_name.strip if full_name.empty? && user.respond_to?(:full_name)
+
+          {
+            id: user.id,
+            firstName: first_name,
+            lastName: last_name,
+            fullName: full_name,
+            username: user.username,
+            email: user.email,
+            emailValidated: user.email_validated,
+            phoneNumber: phone_number_for(user),
+            phoneNumberValidated: phone_number_validated_for(user),
+            roles: user.roles,
+            createdAt: user.created_at&.iso8601,
+            capabilities: capabilities
+          }
+        end
+
+        def self.phone_number_for(user)
+          return nil unless user.respond_to?(:phone_number)
+
+          user.phone_number.presence
+        end
+        private_class_method :phone_number_for
+
+        def self.phone_number_validated_for(user)
+          return false unless user.respond_to?(:phone_number_validated)
+
+          !!user.phone_number_validated
+        end
+        private_class_method :phone_number_validated_for
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      class ChangePasswordResponseSerializer
+        def self.serialize(message: "Password updated successfully.")
+          { message: message }
+        end
+      end
+    end
+  end
+end

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,20 +1,26 @@
-# 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 time it took to complete the logic
-- The status of the logic
 
-Additionally, it provides some convenience methods for logging
-- `log_debug`
-- `log_info`
-- `log_warn`
-- `log_error`
+Lifecycle logging is an `ActiveSupport::Notifications` consumer. Services do not write Start/Finished lines to `Rails.logger`.
+
+Operational notes from services still use `log_info` / `log_warn` / `log_error`, which publish `command_tower.log.*` events. See [Eventing](../../../docs/eventing.md).
 
 ### Argument Validation
 Argument Validation is the powerhouse behind ServiceBase
@@ -39,11 +45,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,82 @@
 # 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_debug("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:)
-        log_info("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
+      log_debug("User Roles: #{user.roles}")
+      authorized = user_role_objects.any? do |_role_name, role_object|
+        result = role_object.authorized?(controller:, method: action, user:)
+        log_debug("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")
+      unless authorized
+        log_warn("controller:#{controller}; method:#{action} -- #{UNAUTHORIZED_MSG}")
+        return Decision.denied(user:, msg: UNAUTHORIZED_MSG)
       end
+
+      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