Aura.Packages (Aura v1.0.1)

View Source

Service module for interacting with Hex Packages

Resources

Summary

Types

per_page()

The number of results per internal page. Aura sets this to 1000.

pkg_opts()

Options to modify a Packages request

pkg_stream_opts()

Options to modify a Package stream request

search_term()

Search term that filters package results

sort_order()

Sorting criteria for response

Functions

add_package_owner(package_name, owner_email, opts \\ [])

Adds a new owner to the list of package owners

get_package(name, opts \\ [])

Grabs a package given its name

get_package_owner(package_name, username, opts \\ [])

Grabs a single package owner by their username

list_package_owners(name, opts \\ [])

Grabs all owners of a given package

remove_package_owner(package_name, owner_email, opts \\ [])

Removes an existing owner from the list of package owners

stream_audit_logs(package_name, opts \\ [])

Streams audit logs, scoped to a package

stream_packages(opts \\ [])

Grabs a stream of packages, given optional criteria

Types

per_page()

@type per_page() :: non_neg_integer()

The number of results per internal page. Aura sets this to 1000.

pkg_opts()

@type pkg_opts() :: [{:repo_url, Aura.Common.repo_url()}]

Options to modify a Packages request

Keys

pkg_stream_opts()

@type pkg_stream_opts() :: [
  repo: Aura.Common.repo_name(),
  page: Aura.Common.start_page(),
  per_page: per_page(),
  sort: sort_order(),
  search: search_term()
]

Options to modify a Package stream request

Keys

search_term()

@type search_term() :: String.t()

Search term that filters package results

By default search will do a wildcard match on the package name and full text search on the package description. If the search string is nerves, package names matching *nerves* will be found and packages having nerves or a stemmed version of the string in the description.

Search can also be performed on specific fields, for example: name:nerves* extra:package,name,postgresql.

The search fields are:

  • name - Package name, can include the wildcard operator * at the end or start of the string.
  • description - Full text search package description.
  • extra - Comma-separated search on extra map in metadata. extra:type,nerves will match {"type": "nerves"}.

sort_order()

@type sort_order() ::
  :name | :recent_downloads | :total_downloads | :inserted_at | :updated_at

Sorting criteria for response

Functions

add_package_owner(package_name, owner_email, opts \\ [])

@spec add_package_owner(
  package_name :: Aura.Common.package_name(),
  owner_email :: Aura.Common.email(),
  opts :: pkg_opts()
) :: :ok | {:error, any()}

Adds a new owner to the list of package owners

Parameters

ParameterDescription
package_nameAura.Common.package_name/0
owner_emailAura.Common.email/0
opts[:repo_url]Aura.Common.repo_url/0

API Details

MethodPathControllerAction
PUT/packages/:package_name/owners/:owner_emailOwnerController:create
PUT/repos/opts[:repo]/packages/:package_name/owners/:owner_emailOwnerController:create

get_package(name, opts \\ [])

@spec get_package(name :: Aura.Common.package_name(), opts :: pkg_opts()) ::
  {:ok, Aura.Model.HexPackage.t()} | {:error, any()}

Grabs a package given its name

Parameters

ParameterDescription
nameAura.Common.package_name/0
opts[:repo_url]Aura.Common.repo_url/0

API Details

MethodPathControllerAction
GET/packages/:namePackageController:show
GET/repos/opts[:repo]/packages/:namePackageController:show

Examples

iex> alias Aura.Packages
iex> {:ok, pkg} = Packages.get_package("decimal", repo_url: "http://localhost:4000/api")
iex> pkg.name
"decimal"

get_package_owner(package_name, username, opts \\ [])

@spec get_package_owner(
  package_name :: Aura.Common.package_name(),
  username :: Aura.Common.username(),
  opts :: pkg_opts()
) :: {:ok, Aura.Model.HexPackageOwner.t()} | {:error, any()}

Grabs a single package owner by their username

Parameters

ParameterDescription
nameAura.Common.package_name/0
usernameAura.Common.username/0
opts[:repo_url]Aura.Common.repo_url/0

API Details

MethodPathControllerAction
GET/packages/:package_name/owners/:usernameOwnerController:show
GET/repos/opts[:repo]/packages/:package_name/owners/:usernameOwnerController:show

Examples

iex> alias Aura.Packages
iex> {:ok, owner} = Packages.get_package_owner("decimal", "eric", repo_url: "http://localhost:4000/api")
iex> owner.email
"eric@example.com"

list_package_owners(name, opts \\ [])

@spec list_package_owners(name :: Aura.Common.package_name(), opts :: pkg_opts()) ::
  {:ok, [Aura.Model.HexPackageOwner.t()]} | {:error, any()}

Grabs all owners of a given package

Parameters

ParameterDescription
nameAura.Common.package_name/0
opts[:repo_url]Aura.Common.repo_url/0

API Details

MethodPathControllerAction
GET/packages/:name/ownersOwnerController:index
GET/repos/opts[:repo]/packages/:name/ownersOwnerController:index

Examples

iex> alias Aura.Packages
iex> {:ok, [owner | _]} =
...>   Packages.list_package_owners("decimal", repo_url: "http://localhost:4000/api")
iex> owner.email
"eric@example.com"

remove_package_owner(package_name, owner_email, opts \\ [])

@spec remove_package_owner(
  package_name :: Aura.Common.package_name(),
  owner_email :: Aura.Common.email(),
  opts :: pkg_opts()
) :: :ok | {:error, any()}

Removes an existing owner from the list of package owners

Parameters

ParameterDescription
package_nameAura.Common.package_name/0
owner_emailAura.Common.email/0
opts[:repo_url]Aura.Common.repo_url/0

API Details

MethodPathControllerAction
DELETE/packages/:package_name/owners/:owner_emailOwnerController:delete
DELETE/repos/opts[:repo]/packages/:package_name/owners/:owner_emailOwnerController:delete

stream_audit_logs(package_name, opts \\ [])

@spec stream_audit_logs(
  package_name :: Aura.Common.package_name(),
  opts :: Aura.Common.audit_opts()
) ::
  Enumerable.t()

Streams audit logs, scoped to a package

Note that the page size is fixed by the API to be 100 per page.

Parameters

ParameterDescription
package_nameAura.Common.package_name/0
opts[:repo_url]Aura.Common.repo_url/0
opts[:page]Aura.Common.start_page/0

API Details

MethodPathControllerAction
GET/packages/:package_name/audit-logsPackageController:audit_logs
GET/repos/opts[:repo]/packages/:package_name/audit-logsPackageController:audit_logs

Examples

iex> alias Aura.Packages
iex> opts = [repo_url: "http://localhost:4000/api"]
iex> audit_logs = Packages.stream_audit_logs("decimal", opts) |> Enum.take(20)
iex> _actions = Enum.map(audit_logs, fn audit_log -> audit_log.action end)

stream_packages(opts \\ [])

@spec stream_packages(opts :: pkg_stream_opts()) :: Enumerable.t()

Grabs a stream of packages, given optional criteria

Parameters

ParameterDescription
opts[:repo_url]Aura.Common.repo_url/0
opts[:page]Aura.Common.start_page/0
opts[:per_page]Aura.Packages.per_page/0
opts[:sort]Aura.Packages.sort_order/0
opts[:search]Aura.Packages.search_term/0

API Details

MethodPathControllerAction
GET/packagesPackageController:index
GET/repos/opts[:repo]/packagesPackageController:index

Examples

# request packages,
#   from the local test instance
#   scoped to the repo "hexpm"
#   sorted by total downloads
#   starting with page 2
iex> alias Aura.Packages
iex> opts = [repo_url: "http://localhost:4000/api", repo: "hexpm",
...>         sort: :total_downloads]
iex> packages = Packages.stream_packages(
...>  opts ++ [page: 2])
iex> Enum.empty?(packages)
false

# Use search term
iex> alias Aura.Packages
iex> opts = [repo_url: "http://localhost:4000/api", repo: "hexpm",
...>         sort: :total_downloads, per_page: 5]
iex> packages = Packages.stream_packages(
...>  opts ++ [search: "nerves"]) |> Enum.take(50)
iex> Enum.empty?(packages)
false