Boop (BoopEx v1.0.0)

Copy Markdown View Source

Send events to a self-hosted Boop server.

Boop is a tiny notification inbox: your app POSTs a small JSON event, Boop stores it and pushes a notification to your phone. This library does one thing — send events reliably without ever taking your application down.

Configuration

config :boop_ex,
  url: System.fetch_env!("BOOP_URL"),
  api_key: System.fetch_env!("BOOP_API_KEY"),
  source: "my_app",              # optional default for every event
  timeout: 10_000,               # ms, default 10_000
  enabled: config_env() == :prod # default true

url and api_key fall back to the BOOP_URL and BOOP_API_KEY environment variables when not configured.

Usage

Boop.send("Deploy complete")

Boop.send(title: "Payment received", body: "£19.99", level: :success, source: "polar",
          data: %{customer_id: "123", amount: 19.99, currency: "GBP"})

Boop.send(%Boop.Event{title: "Backup failed", level: :error, data: %{host: "db-01"}})

Boop.send_async(title: "Cron finished", level: :info)

send/2 returns {:ok, %{id: "evt_...", created_at: ~U[...]}} or {:error, %Boop.Error{}}. send_async/2 returns :ok immediately and never raises.

Summary

Types

result()

Functions

enabled?()

Whether sending is enabled by configuration.

healthy?(opts \\ [])

Checks whether the configured server is reachable (GET /health, no auth).

send(event, opts \\ [])

Sends an event and waits for the server's answer.

send_async(event, opts \\ [])

Sends an event on a supervised task and returns :ok immediately.

Types

result()

@type result() ::
  {:ok, %{id: String.t(), created_at: DateTime.t()}}
  | {:ok, :disabled}
  | {:error, Boop.Error.t()}

Functions

enabled?()

@spec enabled?() :: boolean()

Whether sending is enabled by configuration.

healthy?(opts \\ [])

@spec healthy?(keyword()) :: boolean()

Checks whether the configured server is reachable (GET /health, no auth).

send(event, opts \\ [])

@spec send(
  String.t() | keyword() | map() | Boop.Event.t(),
  keyword()
) :: result()

Sends an event and waits for the server's answer.

Accepts a title string, a keyword list / map of event fields, or a %Boop.Event{}. opts may override :url, :api_key, :timeout, and :enabled for this call.

Never raises: bad input, network failures and server errors all come back as {:error, %Boop.Error{}}. When Boop is disabled it returns {:ok, :disabled}.

send_async(event, opts \\ [])

@spec send_async(
  String.t() | keyword() | map() | Boop.Event.t(),
  keyword()
) :: :ok

Sends an event on a supervised task and returns :ok immediately.

Failures are logged at :warning and never surface to the caller. Use this on hot paths and anywhere a notification must not slow down or break the request.