138 lines
3.7 KiB
Markdown
138 lines
3.7 KiB
Markdown
# 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:
|
|
```sh
|
|
git clone <repo-url>
|
|
cd go-iar-notificator
|
|
```
|
|
|
|
Install dependencies:
|
|
```sh
|
|
go mod tidy
|
|
```
|
|
|
|
### Configuration
|
|
Create a `config.yml` file with your IaR credentials and settings:
|
|
|
|
```yaml
|
|
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:
|
|
```sh
|
|
go run main.go
|
|
```
|
|
|
|
Or build a binary:
|
|
```sh
|
|
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:
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
Run tests for specific packages:
|
|
```sh
|
|
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
|