README

O inovanti-messaging é um pacote desenvolvido para facilitar a troca de mensagens e a integração com serviços externos de envio (SMS, e-mail, notificações, etc.) em projetos Laravel 11. O objetivo é fornecer uma API simples para gerenciar provedores de envio, rastreamento de mensagens e logs, sem complicar o fluxo de desenvolvimento.

graph TD;
    A["📱 **Aplicação Laravel**"] -->|"📤 Cria MessageData"| B["🔧 **MessageService**"]

    B -->|"📩 Tipo: SMS"| C["📨 **TwilioSmsService**"]
    B -->|"💬 Tipo: WhatsApp"| D["🟢 **TwilioWhatsAppService**"]
    B -->|"📧 Tipo: Email"| E[✉️ **SendGridEmailService**]

    C -->|"🔄 Envia para"| F["📡 **Twilio API (SMS)**"]
    D -->|"🔄 Envia para"| G["📡 **Twilio API (WhatsApp)**"]
    E -->|"🔄 Envia para"| H["📡 **SendGrid API**"]

    F -->|"✅ Resposta"| I["📊 **Retorna Status**"]
    G -->|"✅ Resposta"| I["📊 **Retorna Status**"]
    H -->|"✅ Resposta"| I["📊 **Retorna Status**"]

    I -->|"🚀 Dispara Evento"| J["📢 **MessageSent ou MessageFailed**"]

    J -->|"📜 Notifica Aplicação"| K["📝 **Callback/Log**"]

🚀 Instalação

Para instalar este pacote via Composer, utilize o seguinte comando:

composer require inovanti-bank/messaging

⚙️ Configuração

Service Provider

Se você estiver usando o Laravel 11, o próprio framework já pode descobrir automaticamente o provider e a facade. Porém, caso queira registrar manualmente, adicione no array de providers do arquivo config/app.php:

'providers' => [
    // ...
    InovantiBank\Messaging\Providers\MessagingServiceProvider::class,
],

Publicar Configurações (opcional)

Este pacote pode conter um arquivo de configuração que você pode publicar para customizar:

php artisan vendor:publish --provider="InovantiBank\Messaging\Providers\MessagingServiceProvider" --tag="config"

Após isso, edite o arquivo config/messaging.php conforme necessário.

Adicione as seguintes variáveis no .env:

# Twilio
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_SMS_FROM=+1234567890
TWILIO_WHATSAPP_FROM=+1234567890

# SendGrid
SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_FROM_EMAIL=no-reply@seu-dominio.com

🌐 APIs Suportadas

Atualmente, a versão 1.0.0 do inovanti-messaging suporta as seguintes plataformas de envio de mensagens:

API	Tipo de Mensagem	Serviços Disponíveis
Twilio	SMS	`TwilioSmsService`
Twilio	WhatsApp	`TwilioWhatsAppService`
SendGrid	E-mail	`SendGridEmailService`

Estamos constantemente adicionando novos provedores de envio ao pacote. Para obter a lista mais atualizada das APIs suportadas e instruções sobre como configurá-las, consulte o repositório no GitHub.

Se houver suporte a novos provedores, a documentação será atualizada para incluir instruções específicas sobre como utilizá-los.

📩 Uso

Agora o envio de mensagens é feito através de serviços específicos (TwilioSmsService, TwilioWhatsAppService, SendGridEmailService), que são gerenciados pelo MessageService.

Exemplo de Envio de SMS

use InovantiBank\Messaging\Services\MessageService;
use InovantiBank\Messaging\Services\TwilioSmsService;
use InovantiBank\Messaging\Providers\TwilioProvider;
use InovantiBank\Messaging\DTOs\MessageData;
use Illuminate\Events\Dispatcher;

$twilioProvider = new TwilioProvider(
    env('TWILIO_ACCOUNT_SID'),
    env('TWILIO_AUTH_TOKEN')
);

$smsService = new TwilioSmsService($twilioProvider);

$messageService = new MessageService([
    'sms' => $smsService,
], new Dispatcher());

$messageData = new MessageData(
    type: 'sms',
    to: '+5511987654321',
    from: env('TWILIO_SMS_FROM'),
    content: 'Mensagem SMS de teste via Twilio.'
);

// Enviando mensagem
$response = $messageService->send($messageData);

print_r($response);

Exemplo de Envio de WhatsApp

use InovantiBank\Messaging\Services\MessageService;
use InovantiBank\Messaging\Services\TwilioWhatsAppService;
use InovantiBank\Messaging\Providers\TwilioProvider;
use InovantiBank\Messaging\DTOs\MessageData;
use Illuminate\Events\Dispatcher;

$twilioProvider = new TwilioProvider(
    env('TWILIO_ACCOUNT_SID'),
    env('TWILIO_AUTH_TOKEN')
);

$whatsappService = new TwilioWhatsAppService($twilioProvider);

$messageService = new MessageService([
    'whatsapp' => $whatsappService,
], new Dispatcher());

$messageData = new MessageData(
    type: 'whatsapp',
    to: '+5511987654321',
    from: env('TWILIO_WHATSAPP_FROM'),
    content: 'Mensagem de teste via WhatsApp Twilio.'
);

$response = $messageService->send($messageData);

print_r($response);

Exemplo de Envio de E-mail

use InovantiBank\Messaging\Services\MessageService;
use InovantiBank\Messaging\Services\SendGridEmailService;
use InovantiBank\Messaging\Providers\SendGridProvider;
use InovantiBank\Messaging\DTOs\MessageData;
use Illuminate\Events\Dispatcher;

$sendGridProvider = new SendGridProvider(env('SENDGRID_API_KEY'));

$emailService = new SendGridEmailService($sendGridProvider);

$messageService = new MessageService([
    'email' => $emailService,
], new Dispatcher());

$messageData = new MessageData(
    type: 'email',
    to: 'destinatario@example.com',
    from: env('SENDGRID_FROM_EMAIL'),
    content: 'Este é um e-mail de teste enviado via SendGrid.',
    subject: 'Teste de E-mail via SendGrid',
    fromName: 'Inovanti',
    replyTo: 'suporte@example.com',
    replyToName: 'Suporte Inovanti',
    categories: ['transactional', 'credit'],
    customArgs: ['operation' => 'proposal_created'],
    headers: ['X-Trace-Id' => 'trace-123'],
    correlationId: 'proposal-123',
    addCC: ['destinatario2@example.com', 'destinatario3@example.com'],
    addBCC: ['destinatario.oculto@example.com', 'destinatario.oculto1@example.com']
);

$response = $messageService->send($messageData);

print_r($response);

O campo subject é opcional. Para compatibilidade, o assunto informado em metadata['subject'] continua sendo aceito. Quando correlationId é informado, ele também é enviado ao SendGrid como o custom arg correlation_id, facilitando a correlação do envio com os eventos e a atividade da mensagem.

O retorno do envio preserva os campos existentes (status, message_id, to, from, type, http_status, cc e bcc) e inclui o contexto rastreável usado no payload, além de response_headers e response_body do SendGrid. message_id e x_message_id representam o X-Message-ID retornado no aceite do Mail Send. O sg_message_id definitivo é atribuído aos eventos individuais pelo SendGrid e pode ser obtido na atividade da mensagem ou no Event Webhook.

Categorias devem representar agrupamentos gerais. Para identificadores por envio, prefira customArgs ou correlationId. Não envie dados pessoais sensíveis nesses campos, pois o SendGrid não os trata como PII e pode armazená-los por longo prazo.

Para consultar a atividade de uma mensagem pelo ID retornado no envio:

$message = $emailService->getMessageById($response['message_id']);

Essa consulta utiliza a Email Activity Feed API do SendGrid e exige que a conta tenha o histórico adicional contratado e que a API key possua permissão de acesso à atividade de e-mail.

🧪 Testes

O pacote vem com testes unitários simulada para garantir que tudo funcione conforme o esperado. Você pode executar os testes usando PHPUnit:

vendor/bin/phpunit
composer test

Para testes unit:

vendor/bin/phpunit --testsuite=Unit
composer unit

🤝 Contribuindo

Contribuições são bem-vindas! Se você deseja reportar um bug, solicitar um novo recurso ou contribuir com código, fique à vontade para abrir uma issue ou enviar um Pull Request.

Faça um Fork do projeto
Crie sua feature branch: git checkout -b minha-nova-feature
Commit suas mudanças: git commit -m 'Adiciona nova feature'
Faça o push para a branch: git push origin minha-nova-feature
Crie um novo Pull Request

📜 Licença

Este projeto está licenciado sob a MIT license.

inovanti-bank / messaging

Maintainers

Package info

Statistics

Security