bugwatch

# Bugwatch (Elixir)

Official Elixir SDK for [Bugwatch](https://bugwatch.roomylabs.com) error tracking. Zero-dependency (stdlib `:httpc` + `:crypto`).

## Install

```elixir
def deps do
  [{:bugwatch, "~> 0.1.0"}]
end
```

## Quickstart

```elixir
# Start the SDK (GenServer) and initialize
{:ok, _} = Bugwatch.start_link()
:ok = Bugwatch.setup("https://bw-YOUR_KEY@bugwatch-api.loadmindx.com/api/1",
  environment: "production",
  release: "1.0.0"
)

# Capture a message
Bugwatch.capture_message("Payment confirmed", "info")

# Capture an exception
try do
  raise RuntimeError, "boom"
rescue
  e -> Bugwatch.capture_exception(e.__struct__ |> Atom.to_string() |> String.trim_leading("Elixir."), Exception.message(e))
end

# Scope
Bugwatch.set_tag("env", "prod")
Bugwatch.set_user("user-123", %{"plan" => "pro"})
Bugwatch.add_breadcrumb(%{"message" => "clicked", "category" => "ui"})

# IMPORTANT: wait for async sends (short-lived scripts)
Bugwatch.flush()
```

## API

| Function | Description |
|---|---|
| `start_link/1` | Start the SDK GenServer (auto-started by `init/2` if absent) |
| `setup(dsn, opts)` | Initialize with DSN + `environment`, `release`, `sample_rate`, `debug`, `allow_http` |
| `capture_message(msg, level)` | Capture a message; returns client-generated event id |
| `capture_exception(type, value, level)` | Capture an exception type + value |
| `set_tag/2` | Attach a tag to all subsequent events |
| `set_user/2` | Set user context (PII fields stripped) |
| `add_breadcrumb/1` | Add a breadcrumb (capped at 100) |
| `clear_scope/0` | Clear tags, user, breadcrumbs |
| `flush/0` | **Required** — waits for pending async sends |
| `initialized?/0` | Check init state |

## Behavior

- **HTTPS enforced** — `http://` DSNs are rejected unless `allow_http: true` (dev only)
- **PII stripped** — `email`, `ip_address`, `ip`, `username` never leave the host
- **Never fatal** — network failures are swallowed; your app keeps running
- **Async send** — events post in supervised `Task`s; call `flush()` before exit
- **TLS** — verified peer by default; falls back gracefully on restricted OTP builds

## DSN format

```
https://{public_key}@{host}/api/{project_id}
```

The public key is sent as the `X-Bugwatch-Key` header. Find it in **Settings → API keys**.

## Tests

```bash
mix test   # 10/10
```

## License

MIT — see [LICENSE](LICENSE).