Merge pull request #160 from twitch-rs/easy-refresh

easy refresh

Author: Emilgardis

CHANGELOG.md

@@ -4,12 +4,17 @@
 
 ## [Unreleased] - ReleaseDate
 
-[Commits](https://github.com/twitch-rs/twitch_oauth2/compare/v0.15.1...Unreleased)
+[Commits](https://github.com/twitch-rs/twitch_oauth2/compare/v0.15.2...Unreleased)
+
+## [v0.15.2] - 2025-03-05
+
+[Commits](https://github.com/twitch-rs/twitch_oauth2/compare/v0.15.1...v0.15.2)
 
 ### Added
 
 - Added a way to see what scopes are missing in a `validator!()` with `Validator::missing`.
 - Added pretty printing for `validator!()`.
+- Added `UserToken::from_refresh_token` and `UserToken::from_existing_or_refresh_token`
 
 ## [v0.15.1] - 2025-01-12
 

Cargo.lock

@@ -1,12 +1,12 @@
 [package]
 name = "twitch_oauth2"
-version = "0.15.1"
+version = "0.15.2"
 edition = "2021"
 repository = "https://github.com/twitch-rs/twitch_oauth2"
 license = "MIT OR Apache-2.0"
 description = "Oauth2 for Twitch endpoints"
 keywords = ["oauth", "twitch", "async", "asynchronous"]
-documentation = "https://docs.rs/twitch_oauth2/0.15.1"
+documentation = "https://docs.rs/twitch_oauth2/0.15.2"
 readme = "README.md"
 include = [
     "src/*",

Cargo.toml

@@ -1,6 +1,6 @@
 # Twitch OAuth2 | OAuth2 for Twitch endpoints
 
-[![github]](https://github.com/twitch-rs/twitch_oauth2) [![crates-io]](https://crates.io/crates/twitch_oauth2) [![docs-rs]](https://docs.rs/twitch_oauth2/0.15.1/twitch_oauth2)
+[![github]](https://github.com/twitch-rs/twitch_oauth2) [![crates-io]](https://crates.io/crates/twitch_oauth2) [![docs-rs]](https://docs.rs/twitch_oauth2/0.15.2/twitch_oauth2)
 
 [github]: https://img.shields.io/badge/github-twitch--rs/twitch__oauth2-8da0cb?style=for-the-badge&labelColor=555555&logo=github"
 [crates-io]: https://img.shields.io/crates/v/twitch_oauth2.svg?style=for-the-badge&color=fc8d62&logo=rust"

README.md

@@ -48,7 +48,7 @@
 //!
 //! ## HTTP Requests
 //!
-//! To enable client features with a supported http library, enable the http library feature in `twitch_oauth2`, like `twitch_oauth2 = { features = ["reqwest"], version = "0.15.1" }`.
+//! To enable client features with a supported http library, enable the http library feature in `twitch_oauth2`, like `twitch_oauth2 = { features = ["reqwest"], version = "0.15.2" }`.
 //! If you're using [twitch_api](https://crates.io/crates/twitch_api), you can use its [`HelixClient`](https://docs.rs/twitch_api/latest/twitch_api/struct.HelixClient.html) instead of the underlying http client.
 //!
 //!

src/lib.rs

@@ -38,6 +38,17 @@ impl ValidationError<std::convert::Infallible> {
     }
 }
 
+/// Errors for [UserToken::from_refresh_token][crate::UserToken::from_refresh_token] and [UserToken::UserToken::from_existing_or_refresh_token][crate::UserToken::from_existing_or_refresh_token]
+#[derive(thiserror::Error, Debug, displaydoc::Display)]
+#[non_exhaustive]
+#[cfg(feature = "client")]
+pub enum RetrieveTokenError<RE: std::error::Error + Send + Sync + 'static> {
+    /// could not validate token
+    ValidationError(#[from] ValidationError<RE>),
+    /// could not refresh token
+    RefreshTokenError(#[from] RefreshTokenError<RE>),
+}
+
 /// Errors for [AccessToken::revoke_token][crate::AccessTokenRef::revoke_token]
 #[allow(missing_docs)]
 #[derive(thiserror::Error, Debug, displaydoc::Display)]

src/tokens/errors.rs

@@ -4,7 +4,7 @@ use super::errors::ValidationError;
 #[cfg(feature = "client")]
 use super::errors::{
     DeviceUserTokenExchangeError, ImplicitUserTokenExchangeError, RefreshTokenError,
-    UserTokenExchangeError,
+    RetrieveTokenError, UserTokenExchangeError,
 };
 #[cfg(feature = "client")]
 use crate::client::Client;
@@ -112,9 +112,34 @@ impl UserToken {
         Self::from_existing(http_client, access_token, None, None).await
     }
 
-    /// Create a [UserToken] from an existing active user token. Retrieves [`login`](TwitchToken::login), [`client_id`](TwitchToken::client_id) and [`scopes`](TwitchToken::scopes)
+    /// Creates a [UserToken] using a refresh token. Retrieves the [`login`](TwitchToken::login) and [`scopes`](TwitchToken::scopes).
     ///
-    /// If the token is already expired, this function will fail to produce a [`UserToken`] and return [`ValidationError::NotAuthorized`]
+    /// If an active user token is associated with the provided refresh token, this function will invalidate that existing user token.
+    #[cfg(feature = "client")]
+    pub async fn from_refresh_token<C>(
+        http_client: &C,
+        refresh_token: RefreshToken,
+        client_id: ClientId,
+        client_secret: impl Into<Option<ClientSecret>>,
+    ) -> Result<UserToken, RetrieveTokenError<<C as Client>::Error>>
+    where
+        C: Client,
+    {
+        let client_secret: Option<ClientSecret> = client_secret.into();
+        let (access_token, _, refresh_token) = refresh_token
+            .refresh_token(http_client, &client_id, client_secret.as_ref())
+            .await?;
+        Self::from_existing(http_client, access_token, refresh_token, client_secret)
+            .await
+            .map_err(Into::into)
+    }
+
+    /// Create a [UserToken] from an existing active user token. Retrieves [`login`](TwitchToken::login) and [`scopes`](TwitchToken::scopes)
+    ///
+    /// If the token is already expired, this function will fail to produce a [`UserToken`] and return [`ValidationError::NotAuthorized`].
+    /// If you have a refresh token, you can use [`UserToken::from_refresh_token`] to refresh the token if was expired.
+    ///
+    /// Consider using [`UserToken::from_existing_or_refresh_token`] to automatically refresh the token if it is expired.
     ///
     /// # Examples
     ///
@@ -150,6 +175,47 @@ impl UserToken {
             .map_err(|e| e.into_other())
     }
 
+    /// Create a [UserToken] from an existing active user token or refresh token if the access token is expired. Retrieves [`login`](TwitchToken::login), [`client_id`](TwitchToken::client_id) and [`scopes`](TwitchToken::scopes).
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use twitch_oauth2::{AccessToken, ClientId, ClientSecret, RefreshToken, UserToken};
+    /// // Make sure you enable the feature "reqwest" for twitch_oauth2 if you want to use reqwest
+    /// # async {let client = twitch_oauth2::client::DummyClient; stringify!(
+    /// let client = reqwest::Client::builder()
+    ///    .redirect(reqwest::redirect::Policy::none())
+    ///    .build()?;
+    /// # );
+    /// let token = UserToken::from_existing_or_refresh_token(
+    ///     &client,
+    ///     AccessToken::from("my_access_token"),
+    ///     RefreshToken::from("my_refresh_token"),
+    ///     ClientId::from("my_client_id"),
+    ///     ClientSecret::from("my_optional_client_secret"),
+    /// ).await?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())};
+    #[cfg(feature = "client")]
+    pub async fn from_existing_or_refresh_token<C>(
+        http_client: &C,
+        access_token: AccessToken,
+        refresh_token: RefreshToken,
+        client_id: ClientId,
+        client_secret: impl Into<Option<ClientSecret>>,
+    ) -> Result<UserToken, RetrieveTokenError<<C as Client>::Error>>
+    where
+        C: Client,
+    {
+        match access_token.validate_token(http_client).await {
+            Ok(v) => Self::new(access_token, Some(refresh_token), v, client_secret)
+                .map_err(|e| e.into_other().into()),
+            Err(ValidationError::NotAuthorized) => {
+                Self::from_refresh_token(http_client, refresh_token, client_id, client_secret).await
+            }
+            Err(e) => return Err(e.into()),
+        }
+    }
+
     /// Assemble token without checks.
     ///
     /// # Notes