An ergonomic library for investigating the Hex.pm API

Table of Contents

• Installation
• Configuration
• Smoke Test
• Implementation Overview
  • Domains
• Testing
• FAQ

Installation

Add :aura to your list of deps in mix.exs:

{:aura, "~> 1.0"}

Then run mix deps.get to install Aura and its dependencies.

Configuration

config :aura,
  # The hex-compliant backend for Aura to connect to
  # This can also be passed in as an option to all service functions
  # Default: https://hex.pm/api
  # See "Testing" for other options
  repo_url: System.get_env("AURA_REPO_URL", "http://localhost:4000/api"),
  # API secret payload to use when making requests from the hex-compliant backend
  # This cannot be passed in as an option to service functions.
  # Please: Don't put the actual secret payload as plain text in your code.
  # Default: nil
  api_key: System.get_env("HEX_API_KEY")

Smoke Test

# Grab aura
{:ok, package} = Aura.Packages.get_package("aura")
latest_version = package.releases |> hd() |> Map.get(:version)
# Grab aura's latest release
{:ok, release} = Aura.Releases.get_release("aura", latest_version)
{:ok,
 %Aura.Model.HexRelease{
   checksum: "8fb6919a3cf545b10e09bc9b98169cca82468157a5e6b1ebd754e833934b02dd",
   configs: %{
     "erlang.mk" => "dep_aura = hex 0.9.1",
     "mix.exs" => "{:aura, \"~> 0.9.1\"}",
     "rebar.config" => "{aura, \"0.9.1\"}"
   },
   docs_html_url: "https://hexdocs.pm/aura/0.9.1/",
   has_docs: true,
   html_url: "https://hex.pm/packages/aura/0.9.1",
   inserted_at: ~U[2025-06-04 04:51:30.142335Z],
   meta: %{elixir: "~> 1.18", app: "aura", build_tools: ["mix"]},
   package_url: "https://hex.pm/api/packages/aura",
   publisher: %{
     url: "https://hex.pm/api/users/camatcode",
     email: "[email protected]",
     username: "camatcode"
   },
   requirements: [
     %{app: "date_time_parser", optional: false, requirement: "~> 1.2.0"},
     %{app: "proper_case", optional: false, requirement: "~> 1.3"},
     %{app: "req", optional: false, requirement: "~> 0.5.10"}
   ],
   retirement: nil,
   updated_at: ~U[2025-06-04 04:51:33.602905Z],
   version: "0.9.1",
   url: "https://hex.pm/api/packages/aura/releases/0.9.1",
   downloads: 0
 }}

Implementation Overview

Domains

Domain	Hex API Controller	Aura Equivalant	Implemented Actions	Notes
API Key	KeyController	Aura.APIKeys	list, get, create, delete, delete all	Can be scoped to an organization
Organization	OrganizationController	Aura.Orgs	list, get, audit
∟ Org User	OrganizationUserController	"	list, get, add, change role, remove
Package	PackageController	Aura.Packages	stream packages, get, audit	Can be scoped to a repo
∟ Owner	OwnerController	"	list, get, add, remove	Can be scoped to a repo
Release	ReleaseController	Aura.Releases	publish, get, retire, un-retire, delete	Can be scoped to a repo
∟ Doc	DocsController	"	publish, get, delete	Can be scoped to a repo
Repository	RepositoryController	Aura.Repos	list, get
User	UserController	Aura.Users	create, get, get current, reset password, audit	Read create docs carefully for ToS caveat

Testing

Warning

All Aura tests expect to connect to a local hex instance and will purposely crash if it discovers it's testing against hex.pm.

You should be very mindful about issuing requests against a production hex API.

To make this easy, you can docker compose up -d from the root of this repository to launch a local instance of hexpm/hexpm and set the repo_url to http://localhost:4000/api in Configuration.

➜  docker compose up -d
[+] Running 1/1
 ✔ Container hex_beefy  Started                                                                                  0.1s 
➜  curl http://localhost:4000/api | jq
{
  "documentation_url": "http://docs.hexpm.apiary.io",
  "key_url": "http://localhost:4000/api/keys/{name}",
  "keys_url": "http://localhost:4000/api/keys",
  "package_owners_url": "http://localhost:4000/api/packages/{name}/owners",
  "package_release_url": "http://localhost:4000/api/packages/{name}/releases/{version}",
  "package_url": "http://localhost:4000/api/packages/{name}",
  "packages_url": "http://localhost:4000/api/packages"
}

FAQ

Why?

I started this project while exploring all the Hex API does, had trouble understanding it all, so started documenting things as I found them, and wound up with an entire project.

Here are some goals and motivations:

1. Aura is meant to be friendly to Elixir folks.
2. Aura's aim is to be documented to hell and back.
3. The maintainer has larger plans that would use Aura as a base.