Merge branch 'develop' into feat/reporting-reopen

spec/enterprise/lib/captain/tools/faq_lookup_tool_spec.rb

@@ -0,0 +1,120 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Tools::FaqLookupTool, type: :model do
+  let(:account) { create(:account) }
+  let(:assistant) { create(:captain_assistant, account: account) }
+  let(:tool) { described_class.new(assistant) }
+  let(:tool_context) { Struct.new(:state).new({}) }
+
+  before do
+    # Create installation config for OpenAI API key to avoid errors
+    create(:installation_config, name: 'CAPTAIN_OPEN_AI_API_KEY', value: 'test-key')
+
+    # Mock embedding service to avoid actual API calls
+    embedding_service = instance_double(Captain::Llm::EmbeddingService)
+    allow(Captain::Llm::EmbeddingService).to receive(:new).and_return(embedding_service)
+    allow(embedding_service).to receive(:get_embedding).and_return(Array.new(1536, 0.1))
+  end
+
+  describe '#description' do
+    it 'returns the correct description' do
+      expect(tool.description).to eq('Search FAQ responses using semantic similarity to find relevant answers')
+    end
+  end
+
+  describe '#parameters' do
+    it 'returns the correct parameters' do
+      expect(tool.parameters).to have_key(:query)
+      expect(tool.parameters[:query].name).to eq(:query)
+      expect(tool.parameters[:query].type).to eq('string')
+      expect(tool.parameters[:query].description).to eq('The question or topic to search for in the FAQ database')
+    end
+  end
+
+  describe '#perform' do
+    context 'when FAQs exist' do
+      let(:document) { create(:captain_document, assistant: assistant) }
+      let!(:response1) do
+        create(:captain_assistant_response,
+               assistant: assistant,
+               question: 'How to reset password?',
+               answer: 'Click on forgot password link',
+               documentable: document,
+               status: 'approved')
+      end
+      let!(:response2) do
+        create(:captain_assistant_response,
+               assistant: assistant,
+               question: 'How to change email?',
+               answer: 'Go to settings and update email',
+               status: 'approved')
+      end
+
+      before do
+        # Mock nearest_neighbors to return our test responses
+        allow(Captain::AssistantResponse).to receive(:nearest_neighbors).and_return(
+          Captain::AssistantResponse.where(id: [response1.id, response2.id])
+        )
+      end
+
+      it 'searches FAQs and returns formatted responses' do
+        result = tool.perform(tool_context, query: 'password reset')
+
+        expect(result).to include('Question: How to reset password?')
+        expect(result).to include('Answer: Click on forgot password link')
+        expect(result).to include('Question: How to change email?')
+        expect(result).to include('Answer: Go to settings and update email')
+      end
+
+      it 'includes source link when document has external_link' do
+        document.update!(external_link: 'https://help.example.com/password')
+
+        result = tool.perform(tool_context, query: 'password')
+
+        expect(result).to include('Source: https://help.example.com/password')
+      end
+
+      it 'logs tool usage for search' do
+        expect(tool).to receive(:log_tool_usage).with('searching', { query: 'password reset' })
+        expect(tool).to receive(:log_tool_usage).with('found_results', { query: 'password reset', count: 2 })
+
+        tool.perform(tool_context, query: 'password reset')
+      end
+    end
+
+    context 'when no FAQs found' do
+      before do
+        # Return empty result set
+        allow(Captain::AssistantResponse).to receive(:nearest_neighbors).and_return(Captain::AssistantResponse.none)
+      end
+
+      it 'returns no results message' do
+        result = tool.perform(tool_context, query: 'nonexistent topic')
+        expect(result).to eq('No relevant FAQs found for: nonexistent topic')
+      end
+
+      it 'logs tool usage for no results' do
+        expect(tool).to receive(:log_tool_usage).with('searching', { query: 'nonexistent topic' })
+        expect(tool).to receive(:log_tool_usage).with('no_results', { query: 'nonexistent topic' })
+
+        tool.perform(tool_context, query: 'nonexistent topic')
+      end
+    end
+
+    context 'with blank query' do
+      it 'handles empty query' do
+        # Return empty result set
+        allow(Captain::AssistantResponse).to receive(:nearest_neighbors).and_return(Captain::AssistantResponse.none)
+
+        result = tool.perform(tool_context, query: '')
+        expect(result).to eq('No relevant FAQs found for: ')
+      end
+    end
+  end
+
+  describe '#active?' do
+    it 'returns true for public tools' do
+      expect(tool.active?).to be true
+    end
+  end
+end

spec/enterprise/lib/captain/tools/handoff_tool_spec.rb

@@ -0,0 +1,166 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Tools::HandoffTool, type: :model do
+  let(:account) { create(:account) }
+  let(:assistant) { create(:captain_assistant, account: account) }
+  let(:tool) { described_class.new(assistant) }
+  let(:user) { create(:user, account: account) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:contact) { create(:contact, account: account) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox, contact: contact) }
+  let(:tool_context) { Struct.new(:state).new({ conversation: { id: conversation.id } }) }
+
+  describe '#description' do
+    it 'returns the correct description' do
+      expect(tool.description).to eq('Hand off the conversation to a human agent when unable to assist further')
+    end
+  end
+
+  describe '#parameters' do
+    it 'returns the correct parameters' do
+      expect(tool.parameters).to have_key(:reason)
+      expect(tool.parameters[:reason].name).to eq(:reason)
+      expect(tool.parameters[:reason].type).to eq('string')
+      expect(tool.parameters[:reason].description).to eq('The reason why handoff is needed (optional)')
+      expect(tool.parameters[:reason].required).to be false
+    end
+  end
+
+  describe '#perform' do
+    context 'when conversation exists' do
+      context 'with reason provided' do
+        it 'creates a private note with reason and hands off conversation' do
+          reason = 'Customer needs specialized support'
+
+          expect do
+            result = tool.perform(tool_context, reason: reason)
+            expect(result).to eq("Conversation handed off to human support team (Reason: #{reason})")
+          end.to change(Message, :count).by(1)
+        end
+
+        it 'creates message with correct attributes' do
+          reason = 'Customer needs specialized support'
+          tool.perform(tool_context, reason: reason)
+
+          created_message = Message.last
+          expect(created_message.content).to eq(reason)
+          expect(created_message.message_type).to eq('outgoing')
+          expect(created_message.private).to be true
+          expect(created_message.sender).to eq(assistant)
+          expect(created_message.account).to eq(account)
+          expect(created_message.inbox).to eq(inbox)
+          expect(created_message.conversation).to eq(conversation)
+        end
+
+        it 'triggers bot handoff on conversation' do
+          # The tool finds the conversation by ID, so we need to mock the found conversation
+          found_conversation = Conversation.find(conversation.id)
+          scoped_conversations = Conversation.where(account_id: assistant.account_id)
+          allow(Conversation).to receive(:where).with(account_id: assistant.account_id).and_return(scoped_conversations)
+          allow(scoped_conversations).to receive(:find_by).with(id: conversation.id).and_return(found_conversation)
+          expect(found_conversation).to receive(:bot_handoff!)
+
+          tool.perform(tool_context, reason: 'Test reason')
+        end
+
+        it 'logs tool usage with reason' do
+          reason = 'Customer needs help'
+          expect(tool).to receive(:log_tool_usage).with(
+            'tool_handoff',
+            { conversation_id: conversation.id, reason: reason }
+          )
+
+          tool.perform(tool_context, reason: reason)
+        end
+      end
+
+      context 'without reason provided' do
+        it 'creates a private note with nil content and hands off conversation' do
+          expect do
+            result = tool.perform(tool_context)
+            expect(result).to eq('Conversation handed off to human support team')
+          end.to change(Message, :count).by(1)
+
+          created_message = Message.last
+          expect(created_message.content).to be_nil
+        end
+
+        it 'logs tool usage with default reason' do
+          expect(tool).to receive(:log_tool_usage).with(
+            'tool_handoff',
+            { conversation_id: conversation.id, reason: 'Agent requested handoff' }
+          )
+
+          tool.perform(tool_context)
+        end
+      end
+
+      context 'when handoff fails' do
+        before do
+          # Mock the conversation lookup and handoff failure
+          found_conversation = Conversation.find(conversation.id)
+          scoped_conversations = Conversation.where(account_id: assistant.account_id)
+          allow(Conversation).to receive(:where).with(account_id: assistant.account_id).and_return(scoped_conversations)
+          allow(scoped_conversations).to receive(:find_by).with(id: conversation.id).and_return(found_conversation)
+          allow(found_conversation).to receive(:bot_handoff!).and_raise(StandardError, 'Handoff error')
+
+          exception_tracker = instance_double(ChatwootExceptionTracker)
+          allow(ChatwootExceptionTracker).to receive(:new).and_return(exception_tracker)
+          allow(exception_tracker).to receive(:capture_exception)
+        end
+
+        it 'returns error message' do
+          result = tool.perform(tool_context, reason: 'Test')
+          expect(result).to eq('Failed to handoff conversation')
+        end
+
+        it 'captures exception' do
+          exception_tracker = instance_double(ChatwootExceptionTracker)
+          expect(ChatwootExceptionTracker).to receive(:new).with(instance_of(StandardError)).and_return(exception_tracker)
+          expect(exception_tracker).to receive(:capture_exception)
+
+          tool.perform(tool_context, reason: 'Test')
+        end
+      end
+    end
+
+    context 'when conversation does not exist' do
+      let(:tool_context) { Struct.new(:state).new({ conversation: { id: 999_999 } }) }
+
+      it 'returns error message' do
+        result = tool.perform(tool_context, reason: 'Test')
+        expect(result).to eq('Conversation not found')
+      end
+
+      it 'does not create a message' do
+        expect do
+          tool.perform(tool_context, reason: 'Test')
+        end.not_to change(Message, :count)
+      end
+    end
+
+    context 'when conversation state is missing' do
+      let(:tool_context) { Struct.new(:state).new({}) }
+
+      it 'returns error message' do
+        result = tool.perform(tool_context, reason: 'Test')
+        expect(result).to eq('Conversation not found')
+      end
+    end
+
+    context 'when conversation id is nil' do
+      let(:tool_context) { Struct.new(:state).new({ conversation: { id: nil } }) }
+
+      it 'returns error message' do
+        result = tool.perform(tool_context, reason: 'Test')
+        expect(result).to eq('Conversation not found')
+      end
+    end
+  end
+
+  describe '#active?' do
+    it 'returns true for public tools' do
+      expect(tool.active?).to be true
+    end
+  end
+end

spec/services/whatsapp/webhook_setup_service_spec.rb

@@ -24,25 +24,19 @@ describe Whatsapp::WebhookSetupService do
   end
 
   describe '#perform' do
-    context 'when all operations succeed' do
+    context 'when phone number is NOT verified (should register)' do
       before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
         allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
         allow(api_client).to receive(:register_phone_number).with('123456789', 223_456)
         allow(api_client).to receive(:subscribe_waba_webhook)
-          .with(waba_id, anything, 'test_verify_token')
-          .and_return({ 'success' => true })
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
         allow(channel).to receive(:save!)
       end
 
-      it 'registers the phone number' do
+      it 'registers the phone number and sets up webhook' do
         with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
           expect(api_client).to receive(:register_phone_number).with('123456789', 223_456)
-          service.perform
-        end
-      end
-
-      it 'sets up webhook subscription' do
-        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
           expect(api_client).to receive(:subscribe_waba_webhook)
             .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
           service.perform
@@ -50,33 +44,71 @@ describe Whatsapp::WebhookSetupService do
       end
     end
 
-    context 'when phone registration fails' do
+    context 'when phone number IS verified (should NOT register)' do
       before do
-        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
-        allow(api_client).to receive(:register_phone_number)
-          .and_raise('Registration failed')
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(true)
         allow(api_client).to receive(:subscribe_waba_webhook)
-          .and_return({ 'success' => true })
+          .with(waba_id, anything, 'test_verify_token').and_return({ 'success' => true })
       end
 
-      it 'continues with webhook setup' do
+      it 'does NOT register phone, but sets up webhook' do
         with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).not_to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+            .with(waba_id, 'https://app.chatwoot.com/webhooks/whatsapp/+1234567890', 'test_verify_token')
+          service.perform
+        end
+      end
+    end
+
+    context 'when phone_number_verified? raises error' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_raise('API down')
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number)
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'tries to register phone and proceeds with webhook setup' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
           expect(api_client).to receive(:subscribe_waba_webhook)
           expect { service.perform }.not_to raise_error
         end
       end
     end
 
-    context 'when webhook setup fails' do
+    context 'when phone registration fails (not blocking)' do
       before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
+        allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
+        allow(api_client).to receive(:register_phone_number).and_raise('Registration failed')
+        allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
+        allow(channel).to receive(:save!)
+      end
+
+      it 'continues with webhook setup even if registration fails' do
+        with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
+          expect { service.perform }.not_to raise_error
+        end
+      end
+    end
+
+    context 'when webhook setup fails (should raise)' do
+      before do
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
         allow(SecureRandom).to receive(:random_number).with(900_000).and_return(123_456)
         allow(api_client).to receive(:register_phone_number)
-        allow(api_client).to receive(:subscribe_waba_webhook)
-          .and_raise('Webhook failed')
+        allow(api_client).to receive(:subscribe_waba_webhook).and_raise('Webhook failed')
       end
 
       it 'raises an error' do
         with_modified_env FRONTEND_URL: 'https://app.chatwoot.com' do
+          expect(api_client).to receive(:register_phone_number)
+          expect(api_client).to receive(:subscribe_waba_webhook)
           expect { service.perform }.to raise_error(/Webhook setup failed/)
         end
       end
@@ -84,24 +116,25 @@ describe Whatsapp::WebhookSetupService do
 
     context 'when required parameters are missing' do
       it 'raises error when channel is nil' do
-        service = described_class.new(nil, waba_id, access_token)
-        expect { service.perform }.to raise_error(ArgumentError, 'Channel is required')
+        service_invalid = described_class.new(nil, waba_id, access_token)
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'Channel is required')
       end
 
       it 'raises error when waba_id is blank' do
-        service = described_class.new(channel, '', access_token)
-        expect { service.perform }.to raise_error(ArgumentError, 'WABA ID is required')
+        service_invalid = described_class.new(channel, '', access_token)
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'WABA ID is required')
       end
 
       it 'raises error when access_token is blank' do
-        service = described_class.new(channel, waba_id, '')
-        expect { service.perform }.to raise_error(ArgumentError, 'Access token is required')
+        service_invalid = described_class.new(channel, waba_id, '')
+        expect { service_invalid.perform }.to raise_error(ArgumentError, 'Access token is required')
       end
     end
 
     context 'when PIN already exists' do
       before do
         channel.provider_config['verification_pin'] = 123_456
+        allow(api_client).to receive(:phone_number_verified?).with('123456789').and_return(false)
         allow(api_client).to receive(:register_phone_number)
         allow(api_client).to receive(:subscribe_waba_webhook).and_return({ 'success' => true })
         allow(channel).to receive(:save!)