@spec authorization_url(String.t() | nil, scope(), String.t(), String.t() | nil) ::
  String.t()

Returns the authorization URL for the OAuth 2.0 authorization flow.

consumer_key is the Tumblr application's OAuth Consumer Key. If not given, the value set in the application's configuration is used.

scope is a list containing one or more of the following:

• :basic (read permission)
• :write (read and write permissions)
• :offline_access (enables token refreshing)

state is a random generated state. For example, one can be generated as follows:

iex> state_length = 32
iex> :crypto.strong_rand_bytes(state_length)
...> |> Base.url_encode64()
...> |> binary_part(0, state_length)

redirect_uri must be set if multiple redirect URIs are registered. If no value is passed, it tries to read it from the application's configuration, which can be left blank as well.

Examples

iex> consumer_key = "YOUR_CONSUMER_KEY"
iex> scope = [:write, :offline_access]
iex> state = "RANDOM_STATE"
iex> Tumbloire.Auth.authorization_url(consumer_key, scope, state)
"https://www.tumblr.com/oauth2/authorize?client_id=YOUR_CONSUMER_KEY&response_type=code&scope=write+offline_access&state=RANDOM_STATE"

@spec parse_callback(String.t()) ::
  {:ok, {String.t(), String.t()}} | {:error, Tumbloire.Error.t()}

Returns the code and state retrieved from the parsed callback URL.

The state should be checked to make sure it matches the one passed in the authorization URL.

Examples

iex> callback_url = "https://redirect.uri?code=AUTHORIZATION_CODE&state=SHOULD_BE_SENT_STATE"
iex> Tumbloire.Auth.parse_callback(callback_url)
{:ok, {"AUTHORIZATION_CODE", "SHOULD_BE_SENT_STATE"}}

@spec refresh_tokens(String.t() | nil, String.t() | nil, String.t() | nil) ::
  {:ok, {String.t(), String.t() | nil}} | {:error, Tumbloire.Error.t()}

Returns a new pair of access and refresh tokens, or an error.

Represents the /v2/oauth2/token - Refresh Token Grant Request endpoint.

consumer_key and consumer_secret are the Tumblr application's OAuth Consumer Key and Secret Key.

refresh_token is the token received from the Authorization Code Grant Request endpoint.

If they are not given, the values set in the application's configuration are used.

@spec request_token(String.t(), String.t() | nil, String.t() | nil, String.t() | nil) ::
  {:ok, {String.t(), String.t() | nil}} | {:error, Tumbloire.Error.t()}

Returns the access and (if offline_access scope was requested) refresh tokens, or an error.

Represents the /oauth2/token - Authorization Code Grant Request endpoint.

code must be the authorization code received in the callback url.

consumer_key and consumer_secret are the Tumblr application's OAuth Consumer Key and Secret Key. If not given, the values set in the application's configuration are used.

redirect_uri must be set if it was included in the authorization request.