chore: improve plan-based feature handling with plan hierarchy (#11335)

- Refactor HandleStripeEventService to better manage features by plan
- Add constants for features available in each plan tier (Startup,
Business, Enterprise)
- Add channel_instagram to Startup plan features
- Improve downgrade handling to properly disable higher-tier features
- Clean up and optimize tests for maintainability
- Add comprehensive test coverage for plan upgrades and downgrades

---------

Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>

enterprise/app/services/enterprise/billing/handle_stripe_event_service.rb

@@ -1,6 +1,31 @@
 class Enterprise::Billing::HandleStripeEventService
+  CLOUD_PLANS_CONFIG = 'CHATWOOT_CLOUD_PLANS'.freeze
+
+  # Plan hierarchy: Hacker (default) -> Startups -> Business -> Enterprise
+  # Each higher tier includes all features from the lower tiers
+
+  # Basic features available starting with the Startups plan
+  STARTUP_PLAN_FEATURES = %w[
+    inbound_emails
+    help_center
+    campaigns
+    team_management
+    channel_twitter
+    channel_facebook
+    channel_email
+    channel_instagram
+    captain_integration
+  ].freeze
+
+  # Additional features available starting with the Business plan
+  BUSINESS_PLAN_FEATURES = %w[sla custom_roles].freeze
+
+  # Additional features available only in the Enterprise plan
+  ENTERPRISE_PLAN_FEATURES = %w[audit_logs disable_branding].freeze
+
   def perform(event:)
-    ensure_event_context(event)
+    @event = event
+
     case @event.type
     when 'customer.subscription.updated'
       process_subscription_updated
@@ -20,14 +45,12 @@ class Enterprise::Billing::HandleStripeEventService
     return if plan.blank? || account.blank?
 
     update_account_attributes(subscription, plan)
-
-    change_plan_features
+    update_plan_features
     reset_captain_usage
   end
 
   def update_account_attributes(subscription, plan)
     # https://stripe.com/docs/api/subscriptions/object
-
     account.update(
       custom_attributes: {
         stripe_customer_id: subscription.customer,
@@ -48,25 +71,57 @@ class Enterprise::Billing::HandleStripeEventService
     Enterprise::Billing::CreateStripeCustomerService.new(account: account).perform
   end
 
-  def change_plan_features
+  def update_plan_features
     if default_plan?
-      account.disable_features(*features_to_update)
+      disable_all_premium_features
     else
-      account.enable_features(*features_to_update)
+      enable_features_for_current_plan
     end
+
+    # Enable any manually managed features configured in internal_attributes
+    enable_account_manually_managed_features
+
     account.save!
   end
 
+  def disable_all_premium_features
+    # Disable all features (for default Hacker plan)
+    account.disable_features(*STARTUP_PLAN_FEATURES)
+    account.disable_features(*BUSINESS_PLAN_FEATURES)
+    account.disable_features(*ENTERPRISE_PLAN_FEATURES)
+  end
+
+  def enable_features_for_current_plan
+    # First disable all premium features to handle downgrades
+    disable_all_premium_features
+
+    # Then enable features based on the current plan
+    enable_plan_specific_features
+  end
+
   def reset_captain_usage
     account.reset_response_usage
   end
 
-  def ensure_event_context(event)
-    @event = event
-  end
+  def enable_plan_specific_features
+    plan_name = account.custom_attributes['plan_name']
+    return if plan_name.blank?
 
-  def features_to_update
-    %w[inbound_emails help_center campaigns team_management channel_twitter channel_facebook channel_email captain_integration]
+    # Enable features based on plan hierarchy
+    case plan_name
+    when 'Startups'
+      # Startups plan gets the basic features
+      account.enable_features(*STARTUP_PLAN_FEATURES)
+    when 'Business'
+      # Business plan gets Startups features + Business features
+      account.enable_features(*STARTUP_PLAN_FEATURES)
+      account.enable_features(*BUSINESS_PLAN_FEATURES)
+    when 'Enterprise'
+      # Enterprise plan gets all features
+      account.enable_features(*STARTUP_PLAN_FEATURES)
+      account.enable_features(*BUSINESS_PLAN_FEATURES)
+      account.enable_features(*ENTERPRISE_PLAN_FEATURES)
+    end
   end
 
   def subscription
@@ -78,13 +133,22 @@ class Enterprise::Billing::HandleStripeEventService
   end
 
   def find_plan(plan_id)
-    installation_config = InstallationConfig.find_by(name: 'CHATWOOT_CLOUD_PLANS')
-    installation_config.value.find { |config| config['product_id'].include?(plan_id) }
+    cloud_plans = InstallationConfig.find_by(name: CLOUD_PLANS_CONFIG)&.value || []
+    cloud_plans.find { |config| config['product_id'].include?(plan_id) }
   end
 
   def default_plan?
-    installation_config = InstallationConfig.find_by(name: 'CHATWOOT_CLOUD_PLANS')
-    default_plan = installation_config.value.first
-    @account.custom_attributes['plan_name'] == default_plan['name']
+    cloud_plans = InstallationConfig.find_by(name: CLOUD_PLANS_CONFIG)&.value || []
+    default_plan = cloud_plans.first || {}
+    account.custom_attributes['plan_name'] == default_plan['name']
+  end
+
+  def enable_account_manually_managed_features
+    # Get manually managed features from internal attributes using the service
+    service = Internal::Accounts::InternalAttributesService.new(account)
+    features = service.manually_managed_features
+
+    # Enable each feature
+    account.enable_features(*features) if features.present?
   end
 end

enterprise/app/services/internal/accounts/internal_attributes_service.rb

@@ -0,0 +1,68 @@
+class Internal::Accounts::InternalAttributesService
+  attr_reader :account
+
+  # List of keys that can be managed through this service
+  # TODO: Add account_notes field in future
+  # This field can be used to store notes about account on Chatwoot cloud
+  VALID_KEYS = %w[manually_managed_features].freeze
+
+  def initialize(account)
+    @account = account
+  end
+
+  # Get a value from internal_attributes
+  def get(key)
+    validate_key!(key)
+    account.internal_attributes[key]
+  end
+
+  # Set a value in internal_attributes
+  def set(key, value)
+    validate_key!(key)
+
+    # Create a new hash to avoid modifying the original
+    new_attrs = account.internal_attributes.dup || {}
+    new_attrs[key] = value
+
+    # Update the account
+    account.internal_attributes = new_attrs
+    account.save
+  end
+
+  # Get manually managed features
+  def manually_managed_features
+    get('manually_managed_features') || []
+  end
+
+  # Set manually managed features
+  def manually_managed_features=(features)
+    features = [] if features.nil?
+    features = [features] unless features.is_a?(Array)
+
+    # Clean up the array: remove empty strings, whitespace, and validate against valid features
+    valid_features = valid_feature_list
+    features = features.compact
+                       .map(&:strip)
+                       .reject(&:empty?)
+                       .select { |f| valid_features.include?(f) }
+                       .uniq
+
+    set('manually_managed_features', features)
+  end
+
+  # Get list of valid features that can be manually managed
+  def valid_feature_list
+    # Business and Enterprise plan features only
+    Enterprise::Billing::HandleStripeEventService::BUSINESS_PLAN_FEATURES +
+      Enterprise::Billing::HandleStripeEventService::ENTERPRISE_PLAN_FEATURES
+  end
+
+  # Account notes functionality removed for now
+  # Will be re-implemented when UI is ready
+
+  private
+
+  def validate_key!(key)
+    raise ArgumentError, "Invalid internal attribute key: #{key}" unless VALID_KEYS.include?(key)
+  end
+end