Aura (Aura v1.0.1)

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: "cam.cook.codes@gmail.com",
     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

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.