An ergonomic library for investigating the Hex.pm API
Add :aura to your list of deps in mix.exs:
{:aura,"~> 1.0"}Then run mix deps.get to install Aura and its dependencies.
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 optionsrepo_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: nilapi_key: System.get_env("HEX_API_KEY")# 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}}| 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 |
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"
}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:
- Aura is meant to be friendly to Elixir folks.
- Aura's aim is to be documentedto hell and back.
- The maintainer has larger plans that would use Aura as a base.