feat: setup captain limits (#10713)

This pull request introduces several changes to implement and manage
usage limits for the Captain AI service. The key changes include adding
configuration for plan limits, updating error messages, modifying
controllers and models to handle usage limits, and updating tests to
ensure the new functionality works correctly.

## Implementation Checklist

- [x] Ability to configure captain limits per check
- [x] Update response for `usage_limits` to include captain limits
- [x] Methods to increment or reset captain responses limits in the
`limits` column for the `Account` model
- [x] Check documents limit using a count query
- [x] Ensure Captain hand-off if a limit is reached
- [x] Ensure limits are enforced for Copilot Chat
- [x] Ensure limits are reset when stripe webhook comes in 
- [x] Increment usage for FAQ generation and Contact notes
- [x] Ensure documents limit is enforced

These changes ensure that the Captain AI service operates within the defined usage limits for different subscription plans, providing appropriate error messages and handling when limits are exceeded.

enterprise/app/models/captain/document.rb

@@ -20,6 +20,7 @@
 #  index_captain_documents_on_status                          (status)
 #
 class Captain::Document < ApplicationRecord
+  class LimitExceededError < StandardError; end
   self.table_name = 'captain_documents'
 
   belongs_to :assistant, class_name: 'Captain::Assistant'
@@ -35,7 +36,10 @@ class Captain::Document < ApplicationRecord
     available: 1
   }
 
+  before_create :ensure_within_plan_limit
   after_create_commit :enqueue_crawl_job
+  after_create_commit :update_document_usage
+  after_destroy :update_document_usage
   after_commit :enqueue_response_builder_job
   scope :ordered, -> { order(created_at: :desc) }
 
@@ -56,7 +60,16 @@ class Captain::Document < ApplicationRecord
     Captain::Documents::ResponseBuilderJob.perform_later(self)
   end
 
+  def update_document_usage
+    account.update_document_usage
+  end
+
   def ensure_account_id
     self.account_id = assistant&.account_id
   end
+
+  def ensure_within_plan_limit
+    limits = account.usage_limits[:captain][:documents]
+    raise LimitExceededError, 'Document limit exceeded' unless limits[:current_available].positive?
+  end
 end

enterprise/app/models/enterprise/account.rb

@@ -1,11 +1,37 @@
 module Enterprise::Account
+  CAPTAIN_RESPONSES = 'captain_responses'.freeze
+  CAPTAIN_DOCUMENTS = 'captain_documents'.freeze
+  CAPTAIN_RESPONSES_USAGE = 'captain_responses_usage'.freeze
+  CAPTAIN_DOCUMENTS_USAGE = 'captain_documents_usage'.freeze
+
   def usage_limits
     {
       agents: agent_limits.to_i,
-      inboxes: get_limits(:inboxes).to_i
+      inboxes: get_limits(:inboxes).to_i,
+      captain: {
+        documents: get_captain_limits(:documents),
+        responses: get_captain_limits(:responses)
+      }
     }
   end
 
+  def increment_response_usage
+    current_usage = custom_attributes[CAPTAIN_RESPONSES_USAGE].to_i || 0
+    custom_attributes[CAPTAIN_RESPONSES_USAGE] = current_usage + 1
+    save
+  end
+
+  def reset_response_usage
+    custom_attributes[CAPTAIN_RESPONSES_USAGE] = 0
+    save
+  end
+
+  def update_document_usage
+    # this will ensure that the document count is always accurate
+    custom_attributes[CAPTAIN_DOCUMENTS_USAGE] = captain_documents.count
+    save
+  end
+
   def subscribed_features
     plan_features = InstallationConfig.find_by(name: 'CHATWOOT_CLOUD_PLAN_FEATURES')&.value
     return [] if plan_features.blank?
@@ -13,8 +39,58 @@ module Enterprise::Account
     plan_features[plan_name]
   end
 
+  def captain_monthly_limit
+    default_limits = default_captain_limits
+
+    {
+      documents: self[:limits][CAPTAIN_DOCUMENTS] || default_limits['documents'],
+      responses: self[:limits][CAPTAIN_RESPONSES] || default_limits['responses']
+    }.with_indifferent_access
+  end
+
   private
 
+  def get_captain_limits(type)
+    total_count = captain_monthly_limit[type.to_s].to_i
+
+    consumed = if type == :documents
+                 custom_attributes[CAPTAIN_DOCUMENTS_USAGE].to_i || 0
+               else
+                 custom_attributes[CAPTAIN_RESPONSES_USAGE].to_i || 0
+               end
+
+    consumed = 0 if consumed.negative?
+
+    {
+      total_count: total_count,
+      current_available: (total_count - consumed).clamp(0, total_count),
+      consumed: consumed
+    }
+  end
+
+  def default_captain_limits
+    max_limits = { documents: ChatwootApp.max_limit, responses: ChatwootApp.max_limit }.with_indifferent_access
+    zero_limits = { documents: 0, responses: 0 }.with_indifferent_access
+    plan_quota = InstallationConfig.find_by(name: 'CAPTAIN_CLOUD_PLAN_LIMITS')&.value
+
+    # If there are no limits configured, we allow max usage
+    return max_limits if plan_quota.blank?
+
+    # if there is plan_quota configred, but plan_name is not present, we return zero limits
+    return zero_limits if plan_name.blank?
+
+    begin
+      # Now we parse the plan_quota and return the limits for the plan name
+      # but if there's no plan_name present in the plan_quota, we return zero limits
+      plan_quota = JSON.parse(plan_quota) if plan_quota.present?
+      plan_quota[plan_name.downcase] || zero_limits
+    rescue StandardError
+      # if there's any error in parsing the plan_quota, we return max limits
+      # this is to ensure that we don't block the user from using the product
+      max_limits
+    end
+  end
+
   def plan_name
     custom_attributes['plan_name']
   end
@@ -41,7 +117,9 @@ module Enterprise::Account
       'type' => 'object',
       'properties' => {
         'inboxes' => { 'type': 'number' },
-        'agents' => { 'type': 'number' }
+        'agents' => { 'type': 'number' },
+        'captain_responses' => { 'type': 'number' },
+        'captain_documents' => { 'type': 'number' }
       },
       'required' => [],
       'additionalProperties' => false

enterprise/app/models/enterprise/inbox.rb

@@ -6,11 +6,19 @@ module Enterprise::Inbox
   end
 
   def active_bot?
-    super || captain_assistant.present?
+    super || captain_active?
+  end
+
+  def captain_active?
+    captain_assistant.present? && more_responses?
   end
 
   private
 
+  def more_responses?
+    account.usage_limits[:captain][:responses][:current_available].positive?
+  end
+
   def get_agent_ids_over_assignment_limit(limit)
     conversations.open.select(:assignee_id).group(:assignee_id).having("count(*) >= #{limit.to_i}").filter_map(&:assignee_id)
   end