Hermes

Overview

Hermes is a multi-channel notification engine for Go, designed to abstract the complexity of dispatching alerts via Email, SMS, and Webhooks.

It provides a unified interface for messaging, allowing you to switch providers (e.g., from AWS SES to Mailgun, or Twilio to MessageBird) without changing your core application logic. Hermes also includes built-in retry mechanisms, beautiful CLI logging, and context awareness for reliable operations.

Key Features

• Multi-Channel Support: Unified API for Email, SMS, and Webhooks.
• Provider Agnostic: Define your own EmailProvider and SMSProvider interfaces to hook into any external service.
• Resilience: Configurable retry logic with exponential backoff for failed deliveries.
• Beautiful Logging: Integrated with Lipgloss for structured, color-coded terminal output (perfect for CLI tools).
• Interactive UI: Includes components compatible with Bubble Tea for building interactive notification consoles.
• Context Aware: Full support for context.Context to handle cancellation and timeouts.

Installation

go get github.com/yrrrrrf/hermes

Quick Start

Hermes requires you to inject providers. Here is a minimal example using a debug provider:

package main

import (
	"context"
	"fmt"
	"github.com/yrrrrrf/hermes/src"
)

// 1. Implement a Provider (or use a real API client)
type MyProvider struct{}

func (p *MyProvider) SendEmail(ctx context.Context, to, sub, body string) error {
	fmt.Printf("Sending email to %s...\n", to)
	return nil
}

func (p *MyProvider) SendSMS(ctx context.Context, to, body string) error {
	return nil
}

func main() {
	// 2. Initialize Engine
	provider := &MyProvider{}
	
	engine := src.New(src.Config{
		Debug:         true,
		MaxRetries:    3,
		EmailProvider: provider,
		SMSProvider:   provider,
	})

	// 3. Dispatch Message
	msg := src.Message{
		Channel:   src.Email,
		Recipient: "user@example.com",
		Subject:   "Welcome!",
		Body:      "Thanks for joining.",
	}

	if err := engine.Send(context.Background(), msg); err != nil {
		panic(err)
	}
}

Architecture

Hermes relies on interfaces to decouple your app from specific vendors:

type EmailProvider interface {
    SendEmail(ctx context.Context, to, subject, htmlBody string) error
}

type SMSProvider interface {
    SendSMS(ctx context.Context, to, body string) error
}

Usage Examples

See the examples directory for complete implementations:

• Interactive CLI: A full TUI application using Bubble Tea to send messages interactively.
• System Demo: Simulates a system sending alerts with timeouts and logs.

The Argus Ecosystem

Hermes is part of the Argus suite, often used alongside Scribe (for generating PDF attachments) to create complete notification pipelines.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.