https://github.com/jowi-dev/heckler
An open source notification processor in elixir
https://github.com/jowi-dev/heckler
Last synced: 12 months ago
JSON representation
An open source notification processor in elixir
- Host: GitHub
- URL: https://github.com/jowi-dev/heckler
- Owner: jowi-dev
- License: apache-2.0
- Created: 2025-01-01T17:04:36.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-07T21:34:15.000Z (over 1 year ago)
- Last Synced: 2025-04-02T02:46:34.111Z (about 1 year ago)
- Language: Elixir
- Homepage:
- Size: 142 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Heckler
[](https://hex.pm/packages/heckler)
[](https://hexdocs.pm/heckler/)
[](https://github.com/yourusername/heckler/blob/main/LICENSE)
Heckler is a notification library for Elixir applications that makes it easy to send and schedule SMS and push notifications.
## Features
* **SMS Messaging**: Send SMS messages using Twilio
* **Scheduled Notifications**: Schedule messages for future delivery using Oban
* **APNS Support**: Send push notifications to Apple devices (coming soon)
* **Notification Tracking**: All notifications are stored in the database for auditing
* **Flexible Architecture**: Add custom adapters for different messaging providers
## Installation
Add Heckler to your `mix.exs` dependencies:
```elixir
def deps do
[
{:heckler, "~> 0.1.0"},
{:oban, "~> 2.15"}, # Required for scheduling functionality
{:jason, "~> 1.0"}, # Required for JSON encoding/decoding
# Only needed if using certain adapters:
{:httpoison, "~> 2.0"}, # Required for Twilio adapter
{:pigeon, "~> 2.0"} # Required for APNS adapter (coming soon)
]
end
```
## Setup
### 1. Generate Migrations
Run the migration generator to create the required database tables:
```shell
mix heckler.gen.migrations
mix ecto.migrate
```
### 2. Configure Adapters
#### Twilio SMS
```elixir
# In config/config.exs or config/runtime.exs
config :your_app, Heckler.Adapters.Twilio,
account_sid: System.get_env("TWILIO_ACCOUNT_SID"),
auth_token: System.get_env("TWILIO_AUTH_TOKEN"),
from_number: System.get_env("TWILIO_FROM_NUMBER"),
message_service_sid: System.get_env("TWILIO_MESSAGE_SERVICE_SID")
```
### 3. Configure Heckler
```elixir
config :your_app, Heckler,
sms_adapter: Heckler.Adapters.Twilio
```
### 4. Configure Oban for Scheduling
```elixir
config :your_app, Oban,
repo: YourApp.Repo,
plugins: [Oban.Plugins.Pruner],
queues: [notifications: 10]
```
### 5. Add to Supervision Tree
```elixir
# In your application.ex
def start(_type, _args) do
children = [
# ...other children
{Heckler, []}
]
Supervisor.start_link(children, strategy: :one_for_one, name: YourApp.Supervisor)
end
```
## Usage
### Sending an SMS Immediately
```elixir
# Using the basic interface
Heckler.SMS.send("+15551234567", "Hello from Heckler!")
# Using the scheduler (records notification in database)
Heckler.Scheduler.send_sms_now("+15551234567", "Hello with tracking!")
```
### Scheduling an SMS for Later
```elixir
# Schedule an SMS for 30 minutes from now
scheduled_time = DateTime.utc_now() |> DateTime.add(30, :minute)
Heckler.Scheduler.schedule_sms("+15551234567", "This is a scheduled message", scheduled_time)
# Schedule with metadata
Heckler.Scheduler.schedule_sms(
"+15551234567",
"Your order has shipped!",
~U[2023-12-25 12:00:00Z],
metadata: %{order_id: "123456"}
)
```
### Custom Adapters
You can easily create custom SMS adapters:
```elixir
defmodule MyApp.CustomSMSAdapter do
@behaviour Heckler.SMS
def send_sms(to, message) do
# Your implementation here
# Must return {:ok, response} or {:error, reason}
end
end
# Configure Heckler to use your adapter
config :your_app, Heckler,
sms_adapter: MyApp.CustomSMSAdapter
```
## Documentation
Complete documentation is available at [https://hexdocs.pm/heckler](https://hexdocs.pm/heckler).
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
Distributed under the MIT License. See `LICENSE` for more information.
## Acknowledgements
- [Oban](https://github.com/sorentwo/oban) for job scheduling
- [HTTPoison](https://github.com/edgurgel/httpoison) for HTTP requests
- [Pigeon](https://github.com/codedge-llc/pigeon) for APNS integration