Bunnyx

Elixir client for the bunny.net API. Built on Req.

Covers the full bunny.net platform — CDN, edge storage, S3-compatible storage, DNS, video streaming, Shield/WAF, edge scripting, magic containers, billing, and more.

Full typespecs on every public function — Dialyzer-ready with IDE autocompletion
Typed structs — responses parsed into structs with snake_case fields, not raw JSON
Runtime clients — no Application config; pass credentials explicitly for easy multi-account and testing
Validated attrs — snake_case maps or keyword lists, clear errors on typos
Documented — @moduledoc and @doc with usage examples on every module and function

Installation

def deps do
  [
    {:bunnyx, "~> 0.4"}
  ]
end

Quick start

Create a client and pass it to every call. No global config needed — multiple clients with different credentials work side by side.

client = Bunnyx.new(api_key: "sk-...")

# CDN — returns a %Bunnyx.PullZone{} struct
{:ok, zone} = Bunnyx.PullZone.create(client, %{name: "my-zone", origin_url: "https://example.com"})
zone.id      #=> 12345
zone.name    #=> "my-zone"

# DNS
{:ok, dns} = Bunnyx.DnsZone.create(client, %{domain: "example.com"})
{:ok, record} = Bunnyx.DnsRecord.add(client, dns.id, %{type: 0, name: "www", value: "1.2.3.4", ttl: 300})

# Keyword lists work too
Bunnyx.PullZone.create(client, name: "my-zone", origin_url: "https://example.com")

# Typos fail fast
Bunnyx.PullZone.create(client, %{nme: "oops"})
#=> ** (ArgumentError) unknown key :nme. Valid keys: :name, :origin_url, ...

Clients

bunny.net uses different authentication for different services. Bunnyx provides four client types:

Client	Auth	Use for
`Bunnyx.new/1`	Account API key	CDN, DNS, storage zones, video libraries, Shield, billing, and everything else
`Bunnyx.Storage.new/1`	Storage zone password	File upload, download, delete, list
`Bunnyx.S3.new/1`	Zone name + password (SigV4)	S3-compatible storage with multipart uploads
`Bunnyx.Stream.new/1`	Library API key	Video CRUD, upload, collections, captions

# Edge storage — upload and download files
storage = Bunnyx.Storage.new(storage_key: "pw-...", zone: "my-zone")
{:ok, nil} = Bunnyx.Storage.put(storage, "/images/logo.png", image_data)
{:ok, data} = Bunnyx.Storage.get(storage, "/images/logo.png")

# S3-compatible storage
s3 = Bunnyx.S3.new(zone: "my-zone", storage_key: "pw-...", region: "de")
{:ok, nil} = Bunnyx.S3.put(s3, "file.txt", "hello")
{:ok, result} = Bunnyx.S3.list(s3, prefix: "images/")

# Video streaming
stream = Bunnyx.Stream.new(api_key: "lib-key-...", library_id: 12345)
{:ok, video} = Bunnyx.Stream.create(stream, %{title: "My Video"})
{:ok, nil} = Bunnyx.Stream.upload(stream, video.guid, video_binary)

API coverage

Main API (`Bunnyx.new/1`)

CDN: PullZone (CRUD, hostnames, SSL, edge rules, referrers, IP blocking, statistics)
DNS: DnsZone (CRUD, DNSSEC, export/import, statistics), DnsRecord (add, update, delete)
Storage management: StorageZone (CRUD, statistics, password reset)
Video libraries: VideoLibrary (CRUD, API keys, watermarks, referrers, DRM stats)
Cache: Purge (URL and pull zone purging)
Security: Shield (zones, WAF rules, rate limiting, access lists, bot detection, metrics, API Guardian)
Compute: EdgeScript (scripts, code, releases, secrets, variables), MagicContainers (apps, registries, containers, endpoints, volumes)
Account: Billing (details, summary, invoices), Account (affiliate, audit log, search), ApiKey, Logging (CDN + origin logs)
Reference: Statistics (global), Country, Region

Separate clients

Edge storage (Bunnyx.Storage): upload, download, delete, list files
S3 (Bunnyx.S3): PUT, GET, DELETE, HEAD, COPY, ListObjectsV2, multipart uploads
Stream (Bunnyx.Stream): video CRUD, upload, fetch, collections, captions, thumbnails, re-encode, transcription, smart actions, analytics, oEmbed

Error handling

API errors return {:ok, result} or {:error, %Bunnyx.Error{}}. Errors include the HTTP method and path for debugging:

case Bunnyx.PullZone.get(client, 999) do
  {:ok, zone} -> zone
  {:error, %Bunnyx.Error{status: 404}} -> nil
  {:error, error} -> raise "#{error.method} #{error.path}: #{error.message}"
end

Invalid arguments (unknown keys, typos) raise ArgumentError before any HTTP call.

Design

Bunnyx follows Elixir library conventions — no compile-time config, no global state, explicit clients.

Runtime clients, not Application config. Every function takes a client struct. Multiple accounts work in the same BEAM. Tests don't need config stubs.
Built on Req. Retries, compression, JSON, connection pooling via Finch — with per-request :receive_timeout and pass-through :req_opts for anything else.
Typed structs with typespecs. Every public function has @spec. API responses are parsed into structs (%PullZone{}, %DnsZone{}, %Video{}, etc.) with snake_case fields — pattern match and dot-access instead of body["CacheControlMaxAgeOverride"].
Validated attrs. Create/update functions accept maps or keyword lists with snake_case keys, validated at call time. Unknown keys raise ArgumentError with the valid set listed.
Secure by default. Client structs derive Inspect excluding credentials. Error messages sanitize API keys. Response structs with secrets (storage passwords, library API keys) hide sensitive fields.
Telemetry and observability. Every HTTP request emits start/stop/exception events with method, path, status, and duration.

Integration testing

The livebooks/ directory contains per-domain integration tests that exercise every SDK function against the real bunny.net API. Set LB_BUNNY_API_KEY and run the cells.

License

MIT — see LICENSE.

LLM disclosure

The creation of this library was expedited by LLMs, a mix of local and remote models, with strict human supervision. The surface area of the bunny.net API is large and it made the creation of this library feasible. The code and library design follows my own preferences and what I consider to be clean, best practice Elixir code.