evolution_api 1.0.0

data/bin/test_gem.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Script para testar a gem Evolution API localmente
+# Uso: ruby bin/test_gem.rb
+
+require 'bundler/setup'
+require_relative '../lib/evolution_api'
+
+puts "🧪 Testando Evolution API Ruby Client"
+puts "=" * 50
+
+# Configuração para teste
+EvolutionApi.configure do |config|
+  config.base_url = ENV['EVOLUTION_API_URL'] || 'http://localhost:8080'
+  config.api_key = ENV['EVOLUTION_API_KEY']
+  config.timeout = 10
+  config.retry_attempts = 1
+  config.retry_delay = 0.1
+end
+
+client = EvolutionApi.client
+
+# Teste 1: Verificar se a API está acessível
+puts "\n1️⃣ Testando conectividade com a API..."
+begin
+  instances = client.list_instances
+  puts "✅ API acessível! Instâncias encontradas: #{instances.length}"
+rescue EvolutionApi::ConnectionError => e
+  puts "❌ Erro de conexão: #{e.message}"
+  puts "💡 Verifique se a Evolution API está rodando em #{EvolutionApi.config.base_url}"
+  exit 1
+rescue EvolutionApi::AuthenticationError => e
+  puts "❌ Erro de autenticação: #{e.message}"
+  puts "💡 Verifique sua API key"
+  exit 1
+rescue StandardError => e
+  puts "❌ Erro inesperado: #{e.message}"
+  exit 1
+end
+
+# Teste 2: Criar uma instância de teste
+puts "\n2️⃣ Testando criação de instância..."
+test_instance_name = "test_ruby_#{Time.now.to_i}"
+
+begin
+  response = client.create_instance(test_instance_name, {
+    qrcode: true,
+    webhook: 'https://example.com/webhook'
+  })
+  puts "✅ Instância criada: #{test_instance_name}"
+rescue StandardError => e
+  puts "❌ Erro ao criar instância: #{e.message}"
+end
+
+# Teste 3: Obter QR Code
+puts "\n3️⃣ Testando obtenção de QR Code..."
+begin
+  qr_response = client.get_qr_code(test_instance_name)
+  if qr_response['qrcode']
+    puts "✅ QR Code obtido com sucesso!"
+    puts "📱 QR Code: #{qr_response['qrcode'][0..50]}..."
+  else
+    puts "⚠️  QR Code não disponível (instância pode estar conectada)"
+  end
+rescue StandardError => e
+  puts "❌ Erro ao obter QR Code: #{e.message}"
+end
+
+# Teste 4: Verificar status da instância
+puts "\n4️⃣ Testando verificação de status..."
+begin
+  instance_info = client.get_instance(test_instance_name)
+  puts "✅ Status da instância: #{instance_info['status']}"
+  puts "📊 Conectada: #{instance_info['status'] == 'open'}"
+rescue StandardError => e
+  puts "❌ Erro ao verificar status: #{e.message}"
+end
+
+# Teste 5: Testar classes auxiliares
+puts "\n5️⃣ Testando classes auxiliares..."
+
+# Teste da classe Instance
+instance = EvolutionApi::Instance.new(test_instance_name, client)
+puts "✅ Classe Instance criada"
+
+# Teste da classe Message
+sample_message_data = {
+  "id" => "test_id",
+  "key" => {
+    "remoteJid" => "5511999999999@s.whatsapp.net",
+    "fromMe" => false,
+    "id" => "test_message_id"
+  },
+  "message" => {
+    "conversation" => "Teste de mensagem"
+  },
+  "messageTimestamp" => Time.now.to_i,
+  "status" => "received"
+}
+
+message = EvolutionApi::Message.new(sample_message_data, test_instance_name)
+puts "✅ Classe Message criada"
+puts "   Tipo: #{message.type}"
+puts "   Texto: #{message.text}"
+puts "   De: #{message.from}"
+
+# Teste da classe Chat
+sample_chat_data = {
+  "id" => "5511999999999@s.whatsapp.net",
+  "name" => "Teste Chat",
+  "unreadCount" => 0,
+  "isGroup" => false,
+  "isReadOnly" => false,
+  "archived" => false,
+  "pinned" => false
+}
+
+chat = EvolutionApi::Chat.new(sample_chat_data, test_instance_name)
+puts "✅ Classe Chat criada"
+puts "   Nome: #{chat.name}"
+puts "   Grupo: #{chat.group?}"
+
+# Teste da classe Contact
+sample_contact_data = {
+  "id" => "5511999999999@s.whatsapp.net",
+  "name" => "Teste Contato",
+  "pushName" => "Teste",
+  "verifiedName" => nil,
+  "isBusiness" => false,
+  "isEnterprise" => false,
+  "isHighLevelVerified" => false
+}
+
+contact = EvolutionApi::Contact.new(sample_contact_data, test_instance_name)
+puts "✅ Classe Contact criada"
+puts "   Nome: #{contact.display_name}"
+puts "   Business: #{contact.business?}"
+
+# Teste 6: Limpeza
+puts "\n6️⃣ Limpando instância de teste..."
+begin
+  client.delete_instance(test_instance_name)
+  puts "✅ Instância removida: #{test_instance_name}"
+rescue StandardError => e
+  puts "⚠️  Erro ao remover instância: #{e.message}"
+end
+
+puts "\n🎉 Testes concluídos com sucesso!"
+puts "\n📋 Resumo:"
+puts "   ✅ Conectividade com API"
+puts "   ✅ Criação de instância"
+puts "   ✅ Obtenção de QR Code"
+puts "   ✅ Verificação de status"
+puts "   ✅ Classes auxiliares"
+puts "   ✅ Limpeza de recursos"
+
+puts "\n💡 Próximos passos:"
+puts "   1. Configure suas credenciais da Evolution API"
+puts "   2. Execute o exemplo básico: ruby examples/basic_usage.rb"
+puts "   3. Consulte a documentação: https://doc.evolution-api.com/"
+puts "   4. Veja o README.md para mais exemplos"

data/lib/evolution_api/chat.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module EvolutionApi
+  # Classe para representar chats do WhatsApp
+  class Chat
+    attr_reader :id, :name, :unread_count, :is_group, :is_read_only, :archived, :pinned, :instance_name
+
+    def initialize(data, instance_name = nil)
+      @id = data['id']
+      @name = data['name']
+      @unread_count = data['unreadCount']
+      @is_group = data['isGroup']
+      @is_read_only = data['isReadOnly']
+      @archived = data['archived']
+      @pinned = data['pinned']
+      @instance_name = instance_name
+    end
+
+    # Verifica se é um grupo
+    def group?
+      is_group == true
+    end
+
+    # Verifica se é um chat privado
+    def private?
+      !group?
+    end
+
+    # Verifica se tem mensagens não lidas
+    def unread?
+      unread_count&.positive?
+    end
+
+    # Obtém o número de mensagens não lidas
+    def unread_count
+      @unread_count || 0
+    end
+
+    # Verifica se está arquivado
+    def archived?
+      archived == true
+    end
+
+    # Verifica se está fixado
+    def pinned?
+      pinned == true
+    end
+
+    # Verifica se é somente leitura
+    def read_only?
+      is_read_only == true
+    end
+
+    # Obtém o número do chat (remove sufixos)
+    def number
+      return nil unless id
+
+      id.split('@').first
+    end
+
+    # Converte para hash
+    def to_h
+      {
+        id: id,
+        name: name,
+        number: number,
+        unread_count: unread_count,
+        is_group: group?,
+        is_private: private?,
+        is_read_only: read_only?,
+        archived: archived?,
+        pinned: pinned?,
+        instance_name: instance_name
+      }
+    end
+
+    # Converte para JSON
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/evolution_api/client.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module EvolutionApi
+  # Cliente principal para interagir com a Evolution API
+  class Client
+    include HTTParty
+
+    attr_reader :config
+
+    def initialize(config = nil)
+      @config = config || EvolutionApi.config
+      setup_http_client
+    end
+
+    # ==================== INSTÂNCIAS ====================
+
+    # Lista todas as instâncias
+    def list_instances
+      get('/instance/fetchInstances')
+    end
+
+    # Cria uma nova instância
+    def create_instance(instance_name, options = {})
+      body = {
+        instanceName: instance_name,
+        qrcode: options[:qrcode] || true,
+        number: options[:number],
+        token: options[:token],
+        webhook: options[:webhook],
+        webhookByEvents: options[:webhook_by_events] || false,
+        webhookBase64: options[:webhook_base64] || false
+      }.compact
+
+      post('/instance/create', body)
+    end
+
+    # Conecta uma instância
+    def connect_instance(instance_name)
+      post("/instance/connect/#{instance_name}")
+    end
+
+    # Desconecta uma instância
+    def disconnect_instance(instance_name)
+      delete("/instance/logout/#{instance_name}")
+    end
+
+    # Remove uma instância
+    def delete_instance(instance_name)
+      delete("/instance/delete/#{instance_name}")
+    end
+
+    # Obtém informações de uma instância
+    def get_instance(instance_name)
+      get("/instance/fetchInstances/#{instance_name}")
+    end
+
+    # Obtém QR Code de uma instância
+    def get_qr_code(instance_name)
+      get("/instance/connect/#{instance_name}")
+    end
+
+    # ==================== MENSAGENS ====================
+
+    # Envia uma mensagem de texto
+    def send_text_message(instance_name, number, text, options = {})
+      body = {
+        number: number,
+        text: text,
+        options: options
+      }
+
+      post("/message/sendText/#{instance_name}", body)
+    end
+
+    # Envia uma mensagem de imagem
+    def send_image_message(instance_name, number, image_url, caption = nil, options = {})
+      body = {
+        number: number,
+        image: image_url,
+        caption: caption,
+        options: options
+      }.compact
+
+      post("/message/sendImage/#{instance_name}", body)
+    end
+
+    # Envia uma mensagem de áudio
+    def send_audio_message(instance_name, number, audio_url, options = {})
+      body = {
+        number: number,
+        audio: audio_url,
+        options: options
+      }
+
+      post("/message/sendAudio/#{instance_name}", body)
+    end
+
+    # Envia uma mensagem de vídeo
+    def send_video_message(instance_name, number, video_url, caption = nil, options = {})
+      body = {
+        number: number,
+        video: video_url,
+        caption: caption,
+        options: options
+      }.compact
+
+      post("/message/sendVideo/#{instance_name}", body)
+    end
+
+    # Envia um documento
+    def send_document_message(instance_name, number, document_url, caption = nil, options = {})
+      body = {
+        number: number,
+        document: document_url,
+        caption: caption,
+        options: options
+      }.compact
+
+      post("/message/sendDocument/#{instance_name}", body)
+    end
+
+    # Envia uma localização
+    def send_location_message(instance_name, number, latitude, longitude, description = nil)
+      body = {
+        number: number,
+        latitude: latitude,
+        longitude: longitude,
+        description: description
+      }.compact
+
+      post("/message/sendLocation/#{instance_name}", body)
+    end
+
+    # Envia uma mensagem de contato
+    def send_contact_message(instance_name, number, contact_number, contact_name)
+      body = {
+        number: number,
+        contacts: [{
+          number: contact_number,
+          name: contact_name
+        }]
+      }
+
+      post("/message/sendContact/#{instance_name}", body)
+    end
+
+    # Envia uma mensagem de botão
+    def send_button_message(instance_name, number, title, description, buttons)
+      body = {
+        number: number,
+        title: title,
+        description: description,
+        buttons: buttons
+      }
+
+      post("/message/sendButton/#{instance_name}", body)
+    end
+
+    # Envia uma lista de opções
+    def send_list_message(instance_name, number, title, description, sections)
+      body = {
+        number: number,
+        title: title,
+        description: description,
+        sections: sections
+      }
+
+      post("/message/sendList/#{instance_name}", body)
+    end
+
+    # ==================== CHAT ====================
+
+    # Obtém chats de uma instância
+    def get_chats(instance_name)
+      get("/chat/findChats/#{instance_name}")
+    end
+
+    # Obtém mensagens de um chat
+    def get_messages(instance_name, number, options = {})
+      params = {
+        limit: options[:limit] || 50,
+        cursor: options[:cursor]
+      }.compact
+
+      get("/chat/findMessages/#{instance_name}/#{number}", params)
+    end
+
+    # Marca mensagens como lidas
+    def mark_messages_as_read(instance_name, number)
+      post("/chat/markMessageAsRead/#{instance_name}", { number: number })
+    end
+
+    # Arquivar chat
+    def archive_chat(instance_name, number)
+      post("/chat/archiveChat/#{instance_name}", { number: number })
+    end
+
+    # Desarquivar chat
+    def unarchive_chat(instance_name, number)
+      post("/chat/unarchiveChat/#{instance_name}", { number: number })
+    end
+
+    # Deletar chat
+    def delete_chat(instance_name, number)
+      delete("/chat/deleteChat/#{instance_name}/#{number}")
+    end
+
+    # ==================== CONTATOS ====================
+
+    # Obtém contatos de uma instância
+    def get_contacts(instance_name)
+      get("/contact/findContacts/#{instance_name}")
+    end
+
+    # Obtém informações de um contato
+    def get_contact(instance_name, number)
+      get("/contact/findContact/#{instance_name}/#{number}")
+    end
+
+    # Verifica se um número existe no WhatsApp
+    def check_number(instance_name, number)
+      post("/contact/checkNumber/#{instance_name}", { number: number })
+    end
+
+    # Bloqueia um contato
+    def block_contact(instance_name, number)
+      post("/contact/blockContact/#{instance_name}", { number: number })
+    end
+
+    # Desbloqueia um contato
+    def unblock_contact(instance_name, number)
+      post("/contact/unblockContact/#{instance_name}", { number: number })
+    end
+
+    # ==================== WEBHOOK ====================
+
+    # Configura webhook para uma instância
+    def set_webhook(instance_name, webhook_url, events = nil)
+      body = {
+        webhook: webhook_url,
+        webhookByEvents: events ? true : false,
+        webhookBase64: false
+      }
+
+      body[:events] = events if events
+
+      post("/webhook/set/#{instance_name}", body)
+    end
+
+    # Obtém configuração de webhook
+    def get_webhook(instance_name)
+      get("/webhook/find/#{instance_name}")
+    end
+
+    # Remove webhook
+    def delete_webhook(instance_name)
+      delete("/webhook/del/#{instance_name}")
+    end
+
+    # ==================== MÉTODOS HTTP ====================
+
+    private
+
+    def setup_http_client
+      self.class.base_uri config.base_url
+      self.class.headers default_headers
+    end
+
+    def default_headers
+      headers = {
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      }
+
+      headers['apikey'] = config.api_key if config.api_key
+      headers
+    end
+
+    def get(path, params = {})
+      make_request(:get, path, params: params)
+    end
+
+    def post(path, body = {})
+      make_request(:post, path, body: body)
+    end
+
+    def put(path, body = {})
+      make_request(:put, path, body: body)
+    end
+
+    def delete(path)
+      make_request(:delete, path)
+    end
+
+    def make_request(method, path, options = {})
+      retries = 0
+      begin
+        response = self.class.public_send(method, path, options)
+        handle_response(response)
+      rescue HTTParty::Error => e
+        retries += 1
+        if retries <= config.retry_attempts
+          sleep(config.retry_delay)
+          retry
+        else
+          raise ConnectionError, "Erro de conexão após #{config.retry_attempts} tentativas: #{e.message}"
+        end
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        raise TimeoutError, "Timeout na requisição para #{path}"
+      end
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201
+        parse_response(response)
+      when 401
+        raise AuthenticationError.new('Erro de autenticação', response)
+      when 403
+        raise AuthorizationError.new('Acesso negado', response)
+      when 404
+        raise NotFoundError.new('Recurso não encontrado', response)
+      when 422
+        raise ValidationError.new('Erro de validação', response, parse_errors(response))
+      when 429
+        raise RateLimitError.new('Limite de requisições excedido', response)
+      when 500..599
+        raise ServerError.new('Erro interno do servidor', response)
+      else
+        raise Error.new("Erro inesperado: #{response.code}", response, response.code)
+      end
+    end
+
+    def parse_response(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def parse_errors(response)
+      return {} unless response.body
+
+      parsed = JSON.parse(response.body)
+      parsed['errors'] || parsed
+    rescue JSON::ParserError
+      { 'body' => response.body }
+    end
+  end
+end

data/lib/evolution_api/contact.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module EvolutionApi
+  # Classe para representar contatos do WhatsApp
+  class Contact
+    attr_reader :id, :name, :push_name, :verified_name, :is_business, :is_enterprise, :is_high_level_verified,
+                :instance_name
+
+    def initialize(data, instance_name = nil)
+      @id = data['id']
+      @name = data['name']
+      @push_name = data['pushName']
+      @verified_name = data['verifiedName']
+      @is_business = data['isBusiness']
+      @is_enterprise = data['isEnterprise']
+      @is_high_level_verified = data['isHighLevelVerified']
+      @instance_name = instance_name
+    end
+
+    # Verifica se é uma conta business
+    def business?
+      is_business == true
+    end
+
+    # Verifica se é uma conta enterprise
+    def enterprise?
+      is_enterprise == true
+    end
+
+    # Verifica se é uma conta verificada de alto nível
+    def high_level_verified?
+      is_high_level_verified == true
+    end
+
+    # Obtém o número do contato (remove sufixos)
+    def number
+      return nil unless id
+
+      id.split('@').first
+    end
+
+    # Obtém o nome de exibição (prioriza nome verificado, depois push name, depois nome)
+    def display_name
+      verified_name || push_name || name || number
+    end
+
+    # Verifica se tem nome verificado
+    def verified?
+      !verified_name.nil? && !verified_name.empty?
+    end
+
+    # Converte para hash
+    def to_h
+      {
+        id: id,
+        number: number,
+        name: name,
+        push_name: push_name,
+        verified_name: verified_name,
+        display_name: display_name,
+        is_business: business?,
+        is_enterprise: enterprise?,
+        is_high_level_verified: high_level_verified?,
+        verified: verified?,
+        instance_name: instance_name
+      }
+    end
+
+    # Converte para JSON
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end