hex_core

https://hex-core.hexdocs.pm/
Admin
hex_core is the Erlang reference implementation of the Hex package manager specifications, providing...
Tokens:47,999
Snippets:376
Trust Score:9
Update:19 hours ago
Show doc for...
Tokens:
Raw
### get_hex_installs/1 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example of retrieving Hex installation versions CSV, showing a response with version and hash data.

```erlang
> hex_repo:get_hex_installs(hex_core:default_config()).
  {ok, {200, ..., <<"1.0.0,abc123,1.13.0\n1.1.0,def456,1.14.0\n...">>}}
```

--------------------------------

### Example: get/3

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Example call to get a package release, showing the expected success response with status 200 and a detailed map of release information.

```erlang
> hex_api_release:get(hex_core:default_config(), <<"package">>, <<"1.0.0">>).
{ok, {200, ..., #{
     <<"checksum">> => <<"540d210d81f56f17f64309a4896430e727972499b37bd59342dc08d61dff74d8">>,
     <<"docs_html_url">> => <<"https://hexdocs.pm/package/1.0.0/">>,
     <<"downloads">> => 740,<<"has_docs">> => true,
     <<"html_url">> => <<"https://hex.pm/packages/package/1.0.0">>,
     <<"inserted_at">> => <<"2014-12-09T18:32:03Z">>,
     <<"meta">> =>
         #{<<"app">> => <<"package">>,
           <<"build_tools">> => [<<"mix">>]},
     <<"package_url">> => <<"https://hex.pm/api/packages/package">>,
     <<"publisher">> => nil,<<"requirements">> => #{},
     <<"retirement">> => nil,
     <<"updated_at">> => <<"2019-07-28T21:12:11Z">>,
     <<"url">> => <<"https://hex.pm/api/packages/package/releases/1.0.0">>,
     <<"version">> => <<"1.0.0">>
     }}}
```

--------------------------------

### get_names/1 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example of retrieving the names resource, showing a response with a map of packages.

```erlang
> hex_repo:get_names(hex_core:default_config()).
  {ok,{200, ...,
       #{packages => [
             #{name => <<"package1">>},
             #{name => <<"package2">>},
             ...]}}}
```

--------------------------------

### get function example

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Example call to get/2 with a default config and api_organization set to 'acme'. The response shows a 200 status with member details including email, role, url, and username.

```erlang
> hex_api_organization_member:get(hex_core:default_config(), #{api_organization => <<"acme">>}, <<"user">>).
{ok, {200, ..., #{
     <<"email">> => <<"user@example.com">>,
     <<"role">> => <<"admin">>,
     <<"url">> => <<"https://hex.pm/api/users/user">>,
     <<"username">> => <<"user">>
     }}}
```

--------------------------------

### get_docs_to_file/4 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example of fetching docs tarball and writing it to a file, then unpacking from that file.

```erlang
> {ok, {200, _}} = hex_repo:get_docs_to_file(hex_core:default_config(), <<"package1">>, <<"1.0.0">>, "/tmp/docs.tar.gz"),
  > ok = hex_tarball:unpack_docs({file, "/tmp/docs.tar.gz"}, "/tmp/docs").
```

--------------------------------

### get_docs/3 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example of fetching docs tarball and unpacking it, using hex_core:default_config() and hex_tarball:unpack_docs/2.

```erlang
> {ok, {200, _, Docs}} = hex_repo:get_docs(hex_core:default_config(), <<"package1">>, <<"1.0.0">>),
  > hex_tarball:unpack_docs(Docs, "/tmp/docs")
  ok
```

--------------------------------

### Example usage of with_repo

Source: https://hex-core.hexdocs.pm/hex_cli_auth.html

Example showing how to call with_repo with a config and a fun that fetches a tarball.

```erlang
  hex_cli_auth:with_repo(Config, fun(C) ->
      hex_repo:get_tarball(C, <<"ecto">>, <<"3.0.0">>)
  end).
```

--------------------------------

### get_package/2 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Fetches a package resource from the repository. The example shows a successful response with package metadata including releases and dependencies.

```erlang
> hex_repo:get_package(hex_core:default_config(), <<"package1">>).
{ok, {200, ...,
      #{name => <<"package1">>,
        releases => [
            #{checksum => ..., version => <<"0.5.0">>, dependencies => []},
            #{checksum => ..., version => <<"1.0.0">>, dependencies => [
                  #{package => <<"package2">>, optional => true, requirement => <<"~> 0.1">>}
            ]},
      ]}}}
```

--------------------------------

### create_docs example

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Example usage of create_docs/1. It creates a docs tarball from a list of files and returns {ok, <<86,69,...>>}.

```erlang
  > Files = [{"doc/index.html", <<"Docs">>}],
  > hex_tarball:create_docs(Files).
  {ok, <<86,69,...>>}
```

--------------------------------

### client_credentials_token/5 example usage with options

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Shows an example of calling client_credentials_token/5 with an additional option to name the token, demonstrating the optional parameters.

```erlang
3> hex_api_oauth:client_credentials_token(Config, <<"cli">>, ApiKey, <<"api">>, [{name, <<"MyMachine">>}]).
```

--------------------------------

### Example: hex_tarball:create/2

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Example usage of hex_tarball:create/2 with metadata and files, showing the returned tarball and checksums.

```erlang
> Metadata = #{<<"name">> => <<"foo">>, <<"version">> => <<"1.0.0">>},
> Files = [{"src/foo.erl", <<"-module(foo).">>}],
> hex_tarball:create(Metadata, Files).
{ok, #{tarball => <<86,69,...>>,
       outer_checksum => <<40,32,...>>,
       inner_checksum => <<178,12,...>>}}
```

--------------------------------

### get_hex_installs(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets the Hex installation versions CSV from the repository.

```APIDOC
## get_hex_installs(Config)

### Description
Gets the Hex installation versions CSV from the repository.

### Function Signature
```erlang
-spec get_hex_installs(Config) -> {ok, {Status, Headers, CSV}} | {error, term()}.
```

### Parameters
- **Config** (map()) - Required - The Hex configuration.

### Returns
- **{ok, {Status, Headers, CSV}}** - On success, returns a tuple with HTTP status, headers, and the CSV content as a binary.
- **{error, term()}** - On failure, returns an error tuple.

### Example
```erlang
> hex_repo:get_hex_installs(hex_core:default_config()).
{ok, {200, ..., <<"1.0.0,abc123,1.13.0\n1.1.0,def456,1.14.0\n...">>}}
```
```

--------------------------------

### retire/4 example

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Example call to retire a package release, returning {ok, {204, ..., nil}}.

```erlang
> hex_api_release:retire(hex_core:default_config(), <<"package">>, <<"1.0.0">>, Params).
{ok, {204, ..., nil}}
```

--------------------------------

### unpack_docs usage examples

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Shows two example calls: one unpacking to memory and returning a list of {filename, binary} tuples, and one unpacking to a directory path, returning ok.

```erlang
> hex_tarball:unpack_docs(Tarball, memory).
  {ok, [{"index.html", <<"<!doctype>">>}, ...]}
 
  > hex_tarball:unpack_docs(Tarball, "path/to/unpack").
  ok
```

--------------------------------

### get_policy/2 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Fetches a policy resource from the repository. The example shows configuring a custom repo_organization and the resulting response with policy details.

```erlang
> Config = (hex_core:default_config())#{repo_organization => <<"myorg">>},
> hex_repo:get_policy(Config, <<"strict-prod">>).
{ok, {200, ...,
      #{repository => <<"myorg">>,
        name => <<"strict-prod">>,
        visibility => 'VISIBILITY_PUBLIC'}}}
```

--------------------------------

### get_hex_installs(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets Hex installation versions CSV from repository.

```APIDOC
## get_hex_installs(Config)

### Description
Gets Hex installation versions CSV from repository.

### Method
Function

### Endpoint
get_hex_installs(Config)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.

### Response
- **{:ok, binary()}** - The CSV content.
```

--------------------------------

### create/2 usage example

Source: https://hex-core.hexdocs.pm/hex_api_short_url.html

Example call to create/2 with default config and a URL, showing a successful response with status 201 and a short URL in the response map.

```erlang
> hex_api_short_url:create(hex_core:default_config(), <<"https://hex.pm/packages/example">>).
  {ok, {201, ..., #{<<"url">> => <<"https://hex.pm/l/XXXXX">>}}}
```

--------------------------------

### unretire/3 example

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Example call to unretire a package release, returning {ok, {204, ..., nil}}.

```erlang
> hex_api_release:unretire(hex_core:default_config(), <<"package">>, <<"1.0.0">>).
{ok, {204, ..., nil}}
```

--------------------------------

### Example: delete/3

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Example call to delete a package release, showing the expected success response with status 204.

```erlang
> hex_api_release:delete(hex_core:default_config(), <<"package">>, <<"1.0.0">>).
{ok, {204, ..., nil}}
```

--------------------------------

### get_public_key/1 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Fetches the public key from the repository. The example shows a successful response returning the public key.

```erlang
> hex_repo:get_public_key(hex_core:default_config())
{ok, {200, _, PublicKey}}
```

--------------------------------

### with_api usage example

Source: https://hex-core.hexdocs.pm/hex_cli_auth.html

Example call to with_api that publishes a release with write permission, using optional and auth_inline options.

```erlang
  hex_cli_auth:with_api(write, Config, fun(C) ->
      hex_api_release:publish(C, Tarball)
  end, [{optional, false}, {auth_inline, true}]).
```

--------------------------------

### get_versions example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Shows how to retrieve the versions resource from the repository. The output includes a map with a packages list containing package names, retired versions, and available versions.

```erlang
> hex_repo:get_versions(Config).
{ok, {200, ...,
      #{packages => [
            #{name => <<"package1">>, retired => [],
              versions => [<<"1.0.0">>]},
            #{name => <<"package2">>, retired => [<<"0.5.0">>],
              versions => [<<"0.5.0">>, <<"1.0.0">>]},
            ...]}}}
```

--------------------------------

### get(Config, Name, Version)

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Gets a package release. Returns the release details including checksum, URLs, and metadata.

```APIDOC
## get(Config, Name, Version)

### Description
Gets a package release.

### Function Signature
```erlang
-spec get(hex_core:config(), binary(), binary()) -> hex_api:response().
```

### Parameters
- **Config** (hex_core:config()) - Required - Configuration for the Hex API.
- **Name** (binary()) - Required - The name of the package.
- **Version** (binary()) - Required - The version of the release to retrieve.

### Example
```erlang
> hex_api_release:get(hex_core:default_config(), <<"package">>, <<"1.0.0">>).
{ok, {200, ..., #{
     <<"checksum">> => <<"540d210d81f56f17f64309a4896430e727972499b37bd59342dc08d61dff74d8">>,
     <<"docs_html_url">> => <<"https://hexdocs.pm/package/1.0.0/">>,
     <<"downloads">> => 740,
     <<"has_docs">> => true,
     <<"html_url">> => <<"https://hex.pm/packages/package/1.0.0">>,
     <<"inserted_at">> => <<"2014-12-09T18:32:03Z">>,
     <<"meta">> => #{<<"app">> => <<"package">>, <<"build_tools">> => [<<"mix">>]},
     <<"package_url">> => <<"https://hex.pm/api/packages/package">>,
     <<"publisher">> => nil,
     <<"requirements">> => #{},
     <<"retirement">> => nil,
     <<"updated_at">> => <<"2019-07-28T21:12:11Z">>,
     <<"url">> => <<"https://hex.pm/api/packages/package/releases/1.0.0">>,
     <<"version">> => <<"1.0.0">>
}}}
```

--------------------------------

### client_credentials_token/4 example usage

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Shows an example of calling client_credentials_token/4 with a default config, client ID, API key, and scope, returning a successful token response.

```erlang
1> Config = hex_core:default_config().
2> hex_api_oauth:client_credentials_token(Config, <<"cli">>, ApiKey, <<"api">>).
{ok, {200, _, #{ <<"access_token">> => <<"...">>, <<"token_type">> => <<"bearer">>, <<"expires_in">> => 1800, <<"scope">> => <<"api">> }}}
```

--------------------------------

### organization_authorization example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Example usage of organization_authorization, showing a successful response with a verification URI and expiration time.

```erlang
  1> Config = hex_core:default_config().
  2> hex_api_oauth:organization_authorization(Config, [<<"acme">>]).
  {ok, {201, _, #{
      <<"verification_uri">> => <<"https://hex.pm/organizations/authorize?code=...">>,
      <<"expires_in">> => 600
  }}}
```

--------------------------------

### fingerprint_equal/2 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example usage of fingerprint_equal/2, showing a call with a public key and a fingerprint string, returning true.

```erlang
> hex_repo:fingerprint_equal(PublicKeyPem, "SHA256:abc123...").
  true
```

--------------------------------

### get_tarball_to_file example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Shows how to download a tarball to a file and then unpack it using hex_tarball:unpack/2. The example uses hex_core:default_config() and expects a 200 status code.

```erlang
> {ok, {200, _}} = hex_repo:get_tarball_to_file(hex_core:default_config(), <<"package1">>, <<"1.0.0">>, "/tmp/package.tar"),
> {ok, #{metadata := Metadata}} = hex_tarball:unpack({file, "/tmp/package.tar"}, "/tmp/package").
```

--------------------------------

### publish/2 spec and example

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Spec for publish/2 and an example call using hex_core:default_config() and a Tarball variable. The response includes a 200 status and a map with release details.

```erlang
-spec publish(hex_core:config(), binary()) -> hex_api:response().
```

```erlang
  > hex_api_release:publish(hex_core:default_config(), Tarball).
  {ok, {200, ..., #{
       <<"checksum">> => <<"540d210d81f56f17f64309a4896430e727972499b37bd59342dc08d61dff74d8">>,
       <<"docs_html_url">> => <<"https://hexdocs.pm/package/1.0.0/">>,
       <<"downloads">> => 740,<<"has_docs">> => true,
       <<"html_url">> => <<"https://hex.pm/packages/package/1.0.0">>,
       <<"inserted_at">> => <<"2014-12-09T18:32:03Z">>,
       <<"meta">> =>
           #{<<"app">> => <<"package">>,
             <<"build_tools">> => [<<"mix">>]},
       <<"package_url">> => <<"https://hex.pm/api/packages/package">>,
       <<"publisher">> => nil,<<"requirements">> => #{},
       <<"retirement">> => nil,
       <<"updated_at">> => <<"2019-07-28T21:12:11Z">>,
       <<"url">> => <<"https://hex.pm/api/packages/package/releases/1.0.0">>,
       <<"version">> => <<"1.0.0">>
       }}}
```

--------------------------------

### get_tarball/3 example

Source: https://hex-core.hexdocs.pm/hex_repo.html

Fetches a tarball from the repository and unpacks it using hex_tarball:unpack/2. The example shows the full workflow of downloading and extracting a package.

```erlang
> {ok, {200, _, Tarball}} = hex_repo:get_tarball(hex_core:default_config(), <<"package1">>, <<"1.0.0">>),
> {ok, #{metadata := Metadata}} = hex_tarball:unpack(Tarball, "/tmp/package").
```

--------------------------------

### list function example

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Example call to list/1 with a default config and api_organization set to 'acme'. The response shows a 200 status with a list of member maps.

```erlang
> hex_api_organization_member:list(hex_core:default_config(), #{api_organization => <<"acme">>}).
{ok, {200, ..., [#{
     <<"email">> => <<"user@example.com">>,
     <<"role">> => <<"admin">>,
     <<"url">> => <<"https://hex.pm/api/users/user">>,
     <<"username">> => <<"user">>
     }]}}
```

--------------------------------

### publish/3 spec and example

Source: https://hex-core.hexdocs.pm/hex_api_release.html

Spec for publish/3 and an example call with the replace query parameter set to true. The response includes a 201 status and a map with release details.

```erlang
-spec publish(hex_core:config(), binary(), publish_params()) -> hex_api:response().
```

```erlang
  > hex_api_release:publish(hex_core:default_config(), Tarball, [{replace, true}]).
  {ok, {201, ..., #{
       <<"checksum">> => <<"540d210d81f56f17f64309a4896430e727972499b37bd59342dc08d61dff74d8">>,
       <<"docs_html_url">> => <<"https://hexdocs.pm/package/1.0.0/">>,
       <<"downloads">> => 740,<<"has_docs">> => true,
       <<"html_url">> => <<"https://hex.pm/packages/package/1.0.0">>,
       <<"inserted_at">> => <<"2014-12-09T18:32:03Z">>,
       <<"meta">> =>
           #{<<"app">> => <<"package">>,
             <<"build_tools">> => [<<"mix">>]},
       <<"package_url">> => <<"https://hex.pm/api/packages/package">>,
       <<"publisher">> => nil,<<"requirements">> => #{},
       <<"retirement">> => nil,
       <<"updated_at">> => <<"2019-07-28T21:12:11Z">>,
       <<"url">> => <<"https://hex.pm/api/packages/package/releases/1.0.0">>,
       <<"version">> => <<"1.0.0">>
       }}}
```

--------------------------------

### device_auth_flow example usage

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Shows how to call device_auth_flow/4 with a default config, a prompt user callback that prints the verification URI and code, and a scope. The expected return is a map with access_token, refresh_token, and expires_at.

```erlang
1> Config = hex_core:default_config().
2> PromptUser = fun(Uri, Code) ->
         io:format("Visit ~s and enter code: ~s~n", [Uri, Code])
     end.
3> hex_api_oauth:device_auth_flow(Config, <<"cli">>, <<"api:write">>, PromptUser).
{ok, #{
    access_token => <<"...">>,
    refresh_token => <<"...">>,
    expires_at => 1234567890
}}
```

--------------------------------

### fingerprint/1 example usage

Source: https://hex-core.hexdocs.pm/hex_repo.html

Example of calling hex_repo:fingerprint/1 with a PEM-encoded public key, returning a SHA256 fingerprint string.

```erlang
> hex_repo:fingerprint(PublicKeyPem).
"SHA256:abc123..."
```

--------------------------------

### add function example

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Example call to add/3 with a default config and api_organization set to 'acme'. The response shows a 200 status with member details including email, role, url, and username.

```erlang
> hex_api_organization_member:add(hex_core:default_config(), #{api_organization => <<"acme">>}, <<"user">>, write).
{ok, {200, ..., #{
     <<"email">> => <<"user@example.com">>,
     <<"role">> => <<"write">>,
     <<"url">> => <<"https://hex.pm/api/users/user">>,
     <<"username">> => <<"user">>
     }}}
```

--------------------------------

### device_authorization/4 usage example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Shows how to call device_authorization/4 with and without options, including the expected response map with device code, user code, verification URIs, expiration, and polling interval.

```erlang
  1> Config = hex_core:default_config().
  2> hex_api_oauth:device_authorization(Config, <<"cli">>, <<"api:write">>).
  {ok,{200, ..., #{
      <<"device_code">> => <<"...">>,
      <<"user_code">> => <<"ABCD-1234">>,
      <<"verification_uri">> => <<"https://hex.pm/oauth/device">>,
      <<"verification_uri_complete">> => <<"https://hex.pm/oauth/device?user_code=ABCD-1234">>,
      <<"expires_in">> => 600,
      <<"interval">> => 5
  }}}
 
  3> hex_api_oauth:device_authorization(Config, <<"cli">>, <<"api:write">>, [{name, <<"MyMachine">>}]).
```

--------------------------------

### get_package(Config, Name)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets package resource from the repository.

```APIDOC
## get_package(Config, Name)

### Description
Gets package resource from the repository.

### Method
Function

### Endpoint
get_package(Config, Name)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.
- **Name** (string()) - Required - Package name.

### Response
- **{:ok, binary()}** - The package resource content.
```

--------------------------------

### refresh_token/3 usage example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Erlang shell example showing how to refresh an access token using a refresh token. The output shows a successful response with a new access token and refresh token.

```erlang
1> Config = hex_core:default_config().
2> hex_api_oauth:refresh_token(Config, <<"cli">>, RefreshToken).
{ok, {200, _, #{
    <<"access_token">> => <<"...">>,
    <<"refresh_token">> => <<"...">>,
    <<"token_type">> => <<"Bearer">>,
    <<"expires_in">> => 3600
}}}
```

--------------------------------

### get_docs(Config, Name, Version)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets docs tarball from the repository.

```APIDOC
## get_docs(Config, Name, Version)

### Description
Gets docs tarball from the repository.

### Method
Function

### Endpoint
get_docs(Config, Name, Version)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.
- **Name** (string()) - Required - Package name.
- **Version** (string()) - Required - Package version.

### Response
- **{:ok, binary()}** - The docs tarball content.
```

--------------------------------

### get_docs_to_file(Config, Name, Version, Filename)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets docs tarball from the repository and writes it to a file.

```APIDOC
## get_docs_to_file(Config, Name, Version, Filename)

### Description
Gets docs tarball from the repository and writes it to a file.

### Method
Function

### Endpoint
get_docs_to_file(Config, Name, Version, Filename)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.
- **Name** (string()) - Required - Package name.
- **Version** (string()) - Required - Package version.
- **Filename** (string()) - Required - Path to the file to write.

### Response
- **:ok** - Indicates success.
```

--------------------------------

### get_package(Config, Name)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets package resource from the repository. Returns a tuple with HTTP status and a map containing package details including releases and dependencies.

```APIDOC
## get_package(Config, Name)

### Description
Gets package resource from the repository.

### Function Signature
`hex_repo:get_package(Config, Name)`

### Parameters
- **Config** (map) - Required - Configuration map from `hex_core:default_config()`.
- **Name** (binary) - Required - Package name as a binary string.

### Returns
- `{ok, {Status, Headers, Body}}` where Status is HTTP status code, Headers are response headers, and Body is a map with package details.

### Example
```erlang
> hex_repo:get_package(hex_core:default_config(), <<"package1">>).
{ok, {200, ...,
      #{name => <<"package1">>,
        releases => [
            #{checksum => ..., version => <<"0.5.0">>, dependencies => []},
            #{checksum => ..., version => <<"1.0.0">>, dependencies => [
                  #{package => <<"package2">>, optional => true, requirement => <<"~> 0.1">>}
            ]},
      ]}}}
```
```

--------------------------------

### get_versions(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets the versions resource from the repository. This function retrieves a list of packages and their available versions.

```APIDOC
## get_versions(Config)

### Description
Gets versions resource from the repository.

### Function Signature
`hex_repo:get_versions(Config)`

### Parameters
- **Config** (map) - Required - Configuration map for the repository.

### Example
```erlang
> hex_repo:get_versions(Config).
{ok, {200, ...,
      #{packages => [
            #{name => <<"package1">>, retired => [],
              versions => [<<"1.0.0">>]},
            #{name => <<"package2">>, retired => [<<"0.5.0">>],
              versions => [<<"0.5.0">>, <<"1.0.0">>]},
            ...]}}}
```

### Response
Returns a tuple `{ok, {Status, ..., Body}}` where `Status` is the HTTP status code and `Body` is a map containing a `packages` list. Each package entry includes `name`, `retired` (list of retired versions), and `versions` (list of available versions).
```

--------------------------------

### Get default config

Source: https://hex-core.hexdocs.pm/readme.html

Initializes the default configuration for hex_core. This is the starting point for most operations. See the Configuration section for customization.

```erlang
Config = hex_core:default_config().
```

--------------------------------

### oidc_audience example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Example usage of oidc_audience, showing a successful response with the audience 'hexpm'.

```erlang
  1> Config = hex_core:default_config().
  2> hex_api_oauth:oidc_audience(Config).
  {ok, {200, _, #{<<"audience">> => <<"hexpm">>}}}
```

--------------------------------

### get(Config, UsernameOrEmail)

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Gets an organization member. Returns the member's details.

```APIDOC
## get(Config, UsernameOrEmail)

### Description
Gets an organization member.

### Function Signature
```erlang
-spec get(hex_core:config(), binary()) -> hex_api:response().
```

### Parameters
- **Config** (hex_core:config()) - Required - Configuration for the API request.
- **UsernameOrEmail** (binary()) - Required - The username or email of the member to retrieve.

### Example
```erlang
> hex_api_organization_member:get(hex_core:default_config(), #{api_organization => <<"acme">>}, <<"user">>).
{ok, {200, ..., #{
     <<"email">> => <<"user@example.com">>,
     <<"role">> => <<"admin">>,
     <<"url">> => <<"https://hex.pm/api/users/user">>,
     <<"username">> => <<"user">>
     }}}
```

### Response
- **email** (binary()) - The email of the member.
- **role** (binary()) - The role of the member.
- **url** (binary()) - The URL to the member's profile.
- **username** (binary()) - The username of the member.
```

--------------------------------

### Wrapper module excerpt from examples/myapp_hex.erl

Source: https://hex-core.hexdocs.pm/readme.html

Excerpt from a recommended wrapper module that centralizes configuration and API calls. It shows functions for fetching API packages, repo tarballs, and repo versions, plus internal helpers to set the HTTP user agent fragment and optionally add an API key from the HEX_API_KEY environment variable.

```erlang
-module(myapp_hex).
-export([
    get_api_package/1,
    get_repo_tarball/2,
    get_repo_versions/0
]).

%%====================================================================
%% API functions
%%====================================================================

get_api_package(Name) ->
      case hex_api_package:get(config(), Name) of
          {ok, {200, _Headers, Payload}} ->
              {ok, Payload};

          Other ->
              Other
      end.

get_repo_versions() ->
      case hex_repo:get_versions(config()) of
          {ok, {200, _Headers, Payload}} ->
              {ok, maps:get(packages, Payload)};

          Other ->
              Other
      end.

%%====================================================================
%% Internal functions
%%====================================================================

config() ->
    Config1 = hex_core:default_config(),
    Config2 = put_http_config(Config1),
    Config3 = maybe_put_api_key(Config2),
    Config3.

put_http_config(Config) ->
    maps:put(http_user_agent_fragment, <<"(myapp/1.0.0) (httpc)">>, Config).

maybe_put_api_key(Config) ->
    case os:getenv("HEX_API_KEY") of
        false -> Config;
        Key -> maps:put(api_key, Key, Config)
    end.
```

--------------------------------

### create(Metadata, Files, Config)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a package tarball with the given metadata, files, and configuration options.

```APIDOC
## create(Metadata, Files, Config)

### Description
Creates a package tarball with the given metadata, files, and configuration options.

### Function
create(Metadata, Files, Config)

### Parameters
- **Metadata** (map) - Required - The package metadata.
- **Files** (list) - Required - A list of files to include in the tarball.
- **Config** (map) - Required - Configuration options for tarball creation.

### Returns
- A tarball binary.
```

--------------------------------

### create(Metadata, Files, Config)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a package tarball with additional configuration options. Returns the tarball binary along with inner and outer checksums.

```APIDOC
## create(Metadata, Files, Config)

### Description
Creates a package tarball with additional configuration options. Returns the tarball binary along with inner and outer checksums.

### Function Signature
```erlang
-spec create(metadata(), files(), hex_core:config()) ->
                {ok, #{tarball => tarball(), outer_checksum => checksum(), inner_checksum => tarball()}} |
                {error, term()}.
```

### Parameters
- **Metadata** (metadata()) - Required - The package metadata, including name and version.
- **Files** (files()) - Required - A list of files, each given as `{Name, Contents}` with contents as a binary, or `{Name, Path}` with the path of a file, directory, or symbolic link on disk. Optionally, `{Name, ContentsOrPath, #{executable => boolean()}}` sets the mode of a regular file.
- **Config** (hex_core:config()) - Required - Configuration options for the tarball creation.

### Return Value
- On success: `{ok, #{tarball => tarball(), outer_checksum => checksum(), inner_checksum => tarball()}}`
- On failure: `{error, term()}`

### Example
```erlang
> Metadata = #{<<"name">> => <<"foo">>, <<"version">> => <<"1.0.0">>},
> Files = [{"src/foo.erl", <<"-module(foo).">>}],
> hex_tarball:create(Metadata, Files, Config).
{ok, #{tarball => <<86,69,...>>,
       outer_checksum => <<40,32,...>>,
       inner_checksum => <<178,12,...>>}}
```
```

--------------------------------

### get function spec

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Specifies the get/2 function that gets an organization member. It takes a config and a username or email, returning a hex_api:response().

```erlang
-spec get(hex_core:config(), binary()) -> hex_api:response().
```

--------------------------------

### delete function example

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Example call to delete/2 with a default config and api_organization set to 'acme'. The response shows a 204 status with nil body.

```erlang
> hex_api_organization_member:delete(hex_core:default_config(), #{api_organization => <<"acme">>}, <<"user">>).
{ok, {204, ..., nil}}
```

--------------------------------

### create_docs(Files, Config)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a docs tarball with the given files and configuration options.

```APIDOC
## create_docs(Files, Config)

### Description
Creates a docs tarball with the given files and configuration options.

### Function
create_docs(Files, Config)

### Parameters
- **Files** (list) - Required - A list of files to include in the docs tarball.
- **Config** (map) - Required - Configuration options for tarball creation.

### Returns
- A tarball binary.
```

--------------------------------

### create(Metadata, Files)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a package tarball with the given metadata and files.

```APIDOC
## create(Metadata, Files)

### Description
Creates a package tarball with the given metadata and files.

### Function
create(Metadata, Files)

### Parameters
- **Metadata** (map) - Required - The package metadata.
- **Files** (list) - Required - A list of files to include in the tarball.

### Returns
- A tarball binary.
```

--------------------------------

### create(Config, URL)

Source: https://hex-core.hexdocs.pm/hex_api_short_url.html

Creates a short URL for the given URL using the Hex HTTP API. It accepts a configuration and a binary URL, and returns a response containing the short URL.

```APIDOC
## create(Config, URL)

### Description
Creates a short URL for the given URL using the Hex HTTP API.

### Function Signature
```erlang
-spec create(hex_core:config(), binary()) -> hex_api:response().
```

### Parameters
- **Config** (hex_core:config()) - Required - Configuration for the Hex API.
- **URL** (binary()) - Required - The URL to shorten.

### Request Example
```erlang
hex_api_short_url:create(hex_core:default_config(), <<"https://hex.pm/packages/example">>).
```

### Response
#### Success Response (201)
- **url** (binary()) - The shortened URL.

#### Response Example
```erlang
{ok, {201, ..., #{<<"url">> => <<"https://hex.pm/l/XXXXX">>}}}
```
```

--------------------------------

### create(Metadata, Files)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a package tarball from the given metadata and files. Returns the tarball binary along with inner and outer checksums.

```APIDOC
## create(Metadata, Files)

### Description
Creates a package tarball from the given metadata and files. Returns the tarball binary along with inner and outer checksums.

### Function Signature
```erlang
-spec create(metadata(), files()) ->
                {ok, #{tarball => tarball(), outer_checksum => checksum(), inner_checksum => tarball()}} |
                {error, term()}.
```

### Parameters
- **Metadata** (metadata()) - Required - The package metadata, including name and version.
- **Files** (files()) - Required - A list of files, each given as `{Name, Contents}` with contents as a binary, or `{Name, Path}` with the path of a file, directory, or symbolic link on disk. Optionally, `{Name, ContentsOrPath, #{executable => boolean()}}` sets the mode of a regular file.

### Return Value
- On success: `{ok, #{tarball => tarball(), outer_checksum => checksum(), inner_checksum => tarball()}}`
- On failure: `{error, term()}`

### Example
```erlang
> Metadata = #{<<"name">> => <<"foo">>, <<"version">> => <<"1.0.0">>},
> Files = [{"src/foo.erl", <<"-module(foo).">>}],
> hex_tarball:create(Metadata, Files).
{ok, #{tarball => <<86,69,...>>,
       outer_checksum => <<40,32,...>>,
       inner_checksum => <<178,12,...>>}}
```
```

--------------------------------

### update function example

Source: https://hex-core.hexdocs.pm/hex_api_organization_member.html

Example call to update/3 with a default config and api_organization set to 'acme'. The response shows a 200 status with updated member details including the new role.

```erlang
> hex_api_organization_member:update(hex_core:default_config(), #{api_organization => <<"acme">>}, <<"user">>, read).
{ok, {200, ..., #{
     <<"email">> => <<"user@example.com">>,
     <<"role">> => <<"read">>,
     <<"url">> => <<"https://hex.pm/api/users/user">>,
     <<"username">> => <<"user">>
     }}}
```

--------------------------------

### revoke_token/3 usage example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Erlang shell example showing how to revoke an OAuth token. The output shows a 200 OK response regardless of whether the token was found, per RFC 7009.

```erlang
1> Config = hex_core:default_config().
2> hex_api_oauth:revoke_token(Config, <<"cli">>, Token).
{ok, {200, ..., nil}}
```

--------------------------------

### poll_device_token/3 usage example

Source: https://hex-core.hexdocs.pm/hex_api_oauth.html

Erlang shell example showing how to poll the OAuth token endpoint. The output shows a successful response with an access token, refresh token, token type, and expiration.

```erlang
1> Config = hex_core:default_config().
2> hex_api_oauth:poll_device_token(Config, <<"cli">>, DeviceCode).
{ok, {200, _, #{ <<"access_token">> => <<"...">>, <<"refresh_token">> => <<"...">>, <<"token_type">> => <<"Bearer">>, <<"expires_in">> => 3600 }}}
```

--------------------------------

### with_repo(BaseConfig, Fun, Opts)

Source: https://hex-core.hexdocs.pm/hex_cli_auth.html

Executes a function with repository authentication, with additional options.

```APIDOC
## with_repo(BaseConfig, Fun, Opts)

### Description
Execute a function with repository authentication.

### Function Signature
with_repo(BaseConfig, Fun, Opts)

### Parameters
- **BaseConfig** - Base configuration for authentication.
- **Fun** - The function to execute with authentication.
- **Opts** - Additional options for authentication.

### Returns
No explicit return value documented.
```

--------------------------------

### hex_tarball:unpack/3 usage examples

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Three example calls to hex_tarball:unpack/3 showing the different output modes: memory returns contents, none skips contents, and a path string extracts to a directory. Each returns a map with outer_checksum and metadata.

```erlang
> hex_tarball:unpack(Tarball, memory).
  {ok,#{outer_checksum => <<...>>,
        contents => [{"src/foo.erl",<<"-module(foo).">>}],
        metadata => #{<<"name">> => <<"foo">>, ...}}}
 
  > hex_tarball:unpack(Tarball, none).
  {ok,#{outer_checksum => <<...>>,
        metadata => #{<<"name">> => <<"foo">>, ...}}}
 
  > hex_tarball:unpack(Tarball, "path/to/unpack").
  {ok,#{outer_checksum => <<...>>,
        metadata => #{<<"name">> => <<"foo">>, ...}}}
```

--------------------------------

### get_versions(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets versions resource from the repository.

```APIDOC
## get_versions(Config)

### Description
Gets versions resource from the repository.

### Method
Function

### Endpoint
get_versions(Config)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.

### Response
- **{:ok, binary()}** - The versions resource content.
```

--------------------------------

### unpack_docs(Input, Output, Config)

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Unpacks a documentation tarball with configuration options.

```APIDOC
## unpack_docs(Input, Output, Config)

### Description
Unpacks a documentation tarball with configuration options.

### Function
unpack_docs(Input, Output, Config)

### Parameters
- **Input** (binary) - Required - The tarball binary to unpack.
- **Output** (string) - Required - The output directory path.
- **Config** (map) - Required - Configuration options for unpacking.

### Returns
- A result indicating success or failure.
```

--------------------------------

### with_api(Permission, BaseConfig, Fun)

Source: https://hex-core.hexdocs.pm/hex_cli_auth.html

Executes a function with API authentication. Equivalent to with_api(Permission, Config, Fun, []).

```APIDOC
## with_api(Permission, BaseConfig, Fun)

### Description
Executes a function with API authentication. Equivalent to `with_api(Permission, Config, Fun, [])`.

### Function Signature
```erlang
-spec with_api(permission(), hex_core:config(), fun((hex_core:config()) -> Result)) ->
                  Result | {error, auth_error()}
                  when Result :: term().
```

### Parameters
- **Permission** (permission()) - Required - The required permission level (`read` or `write`).
- **BaseConfig** (hex_core:config()) - Required - The base configuration.
- **Fun** (fun((hex_core:config()) -> Result)) - Required - The function to execute with authenticated config.

### Returns
- `Result` on success.
- `{error, auth_error()}` on failure.
```

--------------------------------

### get_public_key(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets the public key from the repository.

```APIDOC
## get_public_key(Config)

### Description
Gets the public key from the repository.

### Method
Function

### Endpoint
get_public_key(Config)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.

### Response
- **{:ok, binary()}** - The public key content.
```

--------------------------------

### with_api(Permission, BaseConfig, Fun, Opts)

Source: https://hex-core.hexdocs.pm/hex_cli_auth.html

Executes a function with API authentication, with additional options.

```APIDOC
## with_api(Permission, BaseConfig, Fun, Opts)

### Description
Execute a function with API authentication.

### Function Signature
with_api(Permission, BaseConfig, Fun, Opts)

### Parameters
- **Permission** - The permission required for the API call.
- **BaseConfig** - Base configuration for authentication.
- **Fun** - The function to execute with authentication.
- **Opts** - Additional options for authentication.

### Returns
No explicit return value documented.
```

--------------------------------

### get_names(Config)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets names resource from the repository.

```APIDOC
## get_names(Config)

### Description
Gets names resource from the repository.

### Method
Function

### Endpoint
get_names(Config)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.

### Response
- **{:ok, binary()}** - The names resource content.
```

--------------------------------

### get_tarball(Config, Name, Version)

Source: https://hex-core.hexdocs.pm/hex_repo.html

Gets tarball from the repository.

```APIDOC
## get_tarball(Config, Name, Version)

### Description
Gets tarball from the repository.

### Method
Function

### Endpoint
get_tarball(Config, Name, Version)

### Parameters
- **Config** (map()) - Required - Configuration for the repository.
- **Name** (string()) - Required - Package name.
- **Version** (string()) - Required - Package version.

### Response
- **{:ok, binary()}** - The tarball content.
```

--------------------------------

### create_docs/2

Source: https://hex-core.hexdocs.pm/hex_tarball.html

Creates a docs tarball with a given configuration. Returns a tarball or an error.

```APIDOC
## create_docs/2

### Description
Creates a docs tarball with a given configuration.

### Function Signature
`create_docs(Files, Config) -> {ok, tarball()} | {error, term()}`

### Parameters
- **Files** (list of {filename(), binary()}) - Required - List of file names and their contents.
- **Config** (hex_core:config()) - Required - Configuration for the tarball creation.

### Returns
- `{ok, tarball()}` - The created tarball.
- `{error, term()}` - An error reason.

### Example
```erlang
Files = [{"doc/index.html", <<"Docs">>}],
hex_tarball:create_docs(Files, Config).
```
```
Tokens:
Raw