Lingo.OAuth2 (Lingo v0.4.2)

Copy Markdown View Source

OAuth2: sending users to authorize the app, trading the code for their token, and calling the API as them (their profile, guilds and guild memberships, connections and linked role data).

url = Lingo.OAuth2.authorize_url(client_id: "123", scopes: ["identify", "role_connections.write"],
        redirect_uri: "https://example.com/callback", state: state)

# on the redirect back
{:ok, token} = Lingo.OAuth2.exchange_code(code, "https://example.com/callback", client)
{:ok, user} = Lingo.OAuth2.get_current_user(token)

client is [client_id: ..., client_secret: ...], from the Developer Portal. Token functions return a Lingo.Type.AccessToken; functions that call the API as the user take it, or its access_token string.

Calls are sent once, outside the bot's rate limit tracking (each token has its own limits); a 429 comes back as an error with its retry_after. No bot needs to be running: calls go to the current bot's API URL when there is one (see Lingo.with_bot/2), and to Discord's otherwise.

Summary

Types

client()
role_connection()

A user's linked role data for an app.

token()

Functions

authorize_url(opts)

The URL to send a user to. Options: :client_id (required), :scopes (list), :redirect_uri, :state (check it when they come back), :prompt ("consent" or "none"), :integration_type (0 guild, 1 user), and for adding a bot :permissions (a bitfield, see Lingo.Permissions.from_list/1), :guild_id and :disable_guild_select.

client_credentials(scopes, client)

A token for the app's owner, without a redirect: the client credentials grant. Team apps may only ask for identify and applications.commands.update.

delete_role_connection(token, application_id)

Removes the user's linked role data for an app (role_connections.write scope).

exchange_code(code, redirect_uri, client)

Trades the code a user came back with for their token.

get_authorization(token)

The token's authorization: :application (partial), :scopes, :expires and, with the identify scope, :user.

get_current_user(token)

The user who authorized (identify scope).

get_guild_member(token, guild_id)

The user's membership in a guild (guilds.members.read scope).

get_role_connection(token, application_id)

The user's linked role data for an app (role_connections.write scope): :platform_name, :platform_username and :metadata.

list_connections(token)

The user's connected accounts (connections scope).

list_guilds(token, opts \\ [])

The user's guilds (guilds scope), partial as in Lingo.Api.User.list_guilds/1. Options: :before, :after, :limit, :with_counts.

refresh(refresh_token, client)

Gets a fresh token with a token's refresh token (or the refresh token itself).

revoke(token, client, hint \\ nil)

Revokes a token, and with it every token of that authorization. Give an AccessToken, or a token string with hint ("access_token" or "refresh_token") saying which it is.

update_role_connection(token, application_id, params)

Sets the user's linked role data for an app (role_connections.write scope): :platform_name, :platform_username and :metadata, keyed by the app's role connection metadata (see Lingo.Api.Application.update_role_connection_metadata/1).

Types

client()

@type client() :: [client_id: String.t(), client_secret: String.t()]

role_connection()

@type role_connection() :: %{
  platform_name: String.t() | nil,
  platform_username: String.t() | nil,
  metadata: %{required(String.t()) => String.t()}
}

A user's linked role data for an app.

token()

@type token() :: Lingo.Type.AccessToken.t() | String.t()

Functions

authorize_url(opts)

@spec authorize_url(keyword()) :: String.t()

The URL to send a user to. Options: :client_id (required), :scopes (list), :redirect_uri, :state (check it when they come back), :prompt ("consent" or "none"), :integration_type (0 guild, 1 user), and for adding a bot :permissions (a bitfield, see Lingo.Permissions.from_list/1), :guild_id and :disable_guild_select.

With a :redirect_uri the URL asks for a code (response_type=code); without one it's a plain bot invite.

client_credentials(scopes, client)

@spec client_credentials([String.t()], client()) ::
  Lingo.Api.result(Lingo.Type.AccessToken.t())

A token for the app's owner, without a redirect: the client credentials grant. Team apps may only ask for identify and applications.commands.update.

delete_role_connection(token, application_id)

@spec delete_role_connection(token(), Lingo.Api.id()) :: Lingo.Api.result()

Removes the user's linked role data for an app (role_connections.write scope).

exchange_code(code, redirect_uri, client)

@spec exchange_code(String.t(), String.t(), client()) ::
  Lingo.Api.result(Lingo.Type.AccessToken.t())

Trades the code a user came back with for their token.

get_authorization(token)

@spec get_authorization(token()) ::
  Lingo.Api.result(%{
    application: Lingo.Type.Application.t(),
    scopes: [String.t()],
    expires: DateTime.t() | nil,
    user: Lingo.Type.User.t() | nil
  })

The token's authorization: :application (partial), :scopes, :expires and, with the identify scope, :user.

get_current_user(token)

@spec get_current_user(token()) :: Lingo.Api.result(Lingo.Type.User.t())

The user who authorized (identify scope).

get_guild_member(token, guild_id)

@spec get_guild_member(token(), Lingo.Api.id()) ::
  Lingo.Api.result(Lingo.Type.Member.t())

The user's membership in a guild (guilds.members.read scope).

get_role_connection(token, application_id)

@spec get_role_connection(token(), Lingo.Api.id()) ::
  Lingo.Api.result(role_connection())

The user's linked role data for an app (role_connections.write scope): :platform_name, :platform_username and :metadata.

list_connections(token)

@spec list_connections(token()) :: Lingo.Api.result([Lingo.Type.Connection.t()])

The user's connected accounts (connections scope).

list_guilds(token, opts \\ [])

@spec list_guilds(
  token(),
  keyword()
) :: Lingo.Api.result([Lingo.Type.Guild.t()])

The user's guilds (guilds scope), partial as in Lingo.Api.User.list_guilds/1. Options: :before, :after, :limit, :with_counts.

refresh(refresh_token, client)

@spec refresh(token(), client()) :: Lingo.Api.result(Lingo.Type.AccessToken.t())

Gets a fresh token with a token's refresh token (or the refresh token itself).

revoke(token, client, hint \\ nil)

@spec revoke(token(), client(), String.t() | nil) :: Lingo.Api.result()

Revokes a token, and with it every token of that authorization. Give an AccessToken, or a token string with hint ("access_token" or "refresh_token") saying which it is.

update_role_connection(token, application_id, params)

@spec update_role_connection(token(), Lingo.Api.id(), Lingo.Api.params()) ::
  Lingo.Api.result(role_connection())

Sets the user's linked role data for an app (role_connections.write scope): :platform_name, :platform_username and :metadata, keyed by the app's role connection metadata (see Lingo.Api.Application.update_role_connection_metadata/1).