@spec authorization_url(map(), map(), String.t(), String.t() | nil, String.t() | nil) ::
  {:ok, String.t()} | {:error, atom()}

Build the OAuth authorization URL for a provider.

Requires client_id to be present in the integration data and the provider to have oauth_config with an auth_url.

@spec exchange_code(map(), map(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

Exchange an authorization code for access and refresh tokens.

@spec fetch_userinfo(map(), String.t()) :: {:ok, map()} | {:error, term()}

Fetch user info from the provider's userinfo endpoint.

Returns a map with at least "email" if available.

@spec generate_state() :: String.t()

Generate a random state token for CSRF protection in OAuth flows.

@spec refresh_access_token(map(), map()) ::
  {:ok, String.t(), map()} | {:error, term()}

Refresh an expired access token using the refresh token.