go-iar-notificator

A Go client and utility for interacting with the IamResponding (IaR) API, designed to send alerts and keep-alive signals for pager groups. This project is structured for extensibility and integration with custom notification workflows.

Features

• API client for IaR with keep-alive and alerting support
• Configurable via YAML and Go structs
• Modular codebase for easy extension
• Comprehensive test coverage
• File system watcher for MP3 files
• Event-driven architecture with custom event bus
• Structured logging with slog
• HTTP client with automatic cookie management

Project Structure

config.yml                # Example configuration file
go.mod                    # Go module file
go.sum                    # Go dependencies checksum
main.go                   # Entry point
bus/
├── bus.go                # Custom event bus implementation
└── bus_test.go           # Event bus tests
client/
├── client.go             # IaR API client
├── response.go           # API response structures
├── request.go            # API request structures
├── client_test.go        # Basic client tests
└── client_api_test.go    # API integration tests with mocked responses
config/
├── config.go             # Configuration loading and structs
└── config_test.go        # Configuration tests
utils/
├── encoder.go            # MP3 to base64 encoder
└── encoder_test.go       # Encoder tests
watcher/
├── watcher.go            # File system watcher for MP3 files
└── watcher_test.go       # Watcher tests

Getting Started

Prerequisites

• Go 1.25 or newer
• Access to the IamResponding API (credentials required)

Installation

Clone the repository:

git clone <repo-url>
cd go-iar-notificator

Install dependencies:

go mod tidy

Configuration

Create a config.yml file with your IaR credentials and settings:

credentials:
  secret_key: "your_secret_key"
  ttd_api_key: "your_ttd_api_key"
directory: "/path/to/watch/for/mp3/files"
watch_debounce_seconds: 5
logging:
  level: "INFO"

Configuration options:

• credentials.secret_key: IaR API secret key
• credentials.ttd_api_key: IaR API key
• directory: Directory to watch for MP3 files
• watch_debounce_seconds: Debounce time for file events (default: 1)
• logging.level: Log level (DEBUG, INFO, WARN, ERROR)

Usage

Build and run the main application:

go run main.go

Or build a binary:

go build -o iar-notificator main.go
./iar-notificator

The application will:

1. Load configuration from config.yml
2. Start watching the specified directory for MP3 files
3. Send keep-alive signals to IaR API at regular intervals
4. Automatically upload MP3 files as alerts when detected

API Integration

The client integrates with the IaR API using GraphQL queries and mutations:

• KeepAlive: Retrieves pager group information and maintains connection
• PreAlert: Creates an alert entry
• Alert: Uploads audio data to an existing alert

API responses are parsed and used to populate internal state for subsequent requests.

Testing

Run all tests:

go test ./...

Run tests for specific packages:

go test ./client
go test ./config
go test ./bus
go test ./watcher
go test ./utils

The test suite includes:

• Unit tests for all core functionality
• Integration tests with mocked HTTP responses
• File system watcher tests
• Configuration loading tests
• Event bus concurrency tests

Dependencies

• resty.dev/v3: HTTP client for API requests
• github.com/fsnotify/fsnotify: File system watching
• gopkg.in/yaml.v3: YAML configuration parsing

License

MIT License

Author

Alex Savin