Merge #78

78: add some convenience functions r=Emilgardis a=Emilgardis



Co-authored-by: Emil Gardström <emil.gardstrom@gmail.com>

Author: bors[bot]

src/helix/client_ext.rs

@@ -0,0 +1,88 @@
+//! Convenience functions for [HelixClient]
+
+use crate::helix::{self, ClientRequestError, HelixClient};
+use crate::types;
+use twitch_oauth2::TwitchToken;
+
+type ClientError<'a, C> = ClientRequestError<<C as crate::HttpClient<'a>>::Error>;
+
+// TODO: Consider moving these into the specific modules where the request is defined. Preferably backed by a macro
+
+impl<'a, C: crate::HttpClient<'a>> HelixClient<'a, C> {
+    /// Get [User](helix::users::User) from user login
+    pub async fn get_user_from_login<T>(
+        &'a self,
+        login: types::UserName,
+        token: &T,
+    ) -> Result<Option<helix::users::User>, ClientError<'a, C>>
+    where
+        T: TwitchToken + ?Sized,
+    {
+        self.req_get(
+            helix::users::GetUsersRequest::builder()
+                .login(vec![login])
+                .build(),
+            token,
+        )
+        .await
+        .map(|response| response.first())
+    }
+
+    /// Get [User](helix::users::User) from user id
+    pub async fn get_user_from_id<T>(
+        &'a self,
+        id: types::UserId,
+        token: &T,
+    ) -> Result<Option<helix::users::User>, ClientError<'a, C>>
+    where
+        T: TwitchToken + ?Sized,
+    {
+        self.req_get(
+            helix::users::GetUsersRequest::builder()
+                .id(vec![id])
+                .build(),
+            token,
+        )
+        .await
+        .map(|response| response.first())
+    }
+
+    /// Get [ChannelInformation](helix::channels::ChannelInformation) from a broadcasters login
+    pub async fn get_channel_from_login<T>(
+        &'a self,
+        login: types::UserName,
+        token: &T,
+    ) -> Result<Option<helix::channels::ChannelInformation>, ClientError<'a, C>>
+    where
+        T: TwitchToken + ?Sized,
+    {
+        if let Some(user) = self.get_user_from_login(login, token).await? {
+            self.get_channel_from_id(user.id, token).await
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Get [ChannelInformation](helix::channels::ChannelInformation) from a broadcasters id
+    pub async fn get_channel_from_id<T>(
+        &'a self,
+        id: types::UserId,
+        token: &T,
+    ) -> Result<Option<helix::channels::ChannelInformation>, ClientError<'a, C>>
+    where
+        T: TwitchToken + ?Sized,
+    {
+        self.req_get(
+            helix::channels::GetChannelInformationRequest::builder()
+                .broadcaster_id(id)
+                .build(),
+            token,
+        )
+        .await
+        .map(|response| response.first())
+    }
+}
+
+/*
+    pub async fn get_xxxx<T>(&'a self, _:_, token: &T) -> Result<_, ClientError<'a, C>> where T: TwitchToken + ?Sized {todo!()}
+*/

src/helix/mod.rs

@@ -31,6 +31,9 @@ use serde::Deserialize;
 use std::{convert::TryInto, str::FromStr};
 #[cfg(feature = "twitch_oauth2")]
 use twitch_oauth2::TwitchToken;
+#[cfg(all(feature = "client"))]
+#[cfg_attr(nightly, doc(cfg(all(feature = "client", feature = "helix"))))]
+pub mod client_ext;
 
 pub mod bits;
 pub mod channels;
@@ -74,6 +77,23 @@ pub use twitch_oauth2::Scope;
 /// ```
 ///
 /// See [`HttpClient`][crate::HttpClient] for implemented http clients, you can also define your own if needed.
+///
+/// # Examples
+///
+/// Get a [user](users::User) from their login name.
+///
+/// ```rust,no_run
+/// # #[tokio::main]
+/// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+/// # pub mod reqwest {pub type Client = twitch_api2::client::DummyHttpClient;}
+/// # let token = twitch_oauth2::AccessToken::new("validtoken".to_string());
+/// # let token = twitch_oauth2::UserToken::from_existing(twitch_oauth2::dummy_http_client, token, None, None).await?;
+/// use twitch_api2::helix::{HelixClient, users::User};
+/// let helix: HelixClient<'static, reqwest::Client> = HelixClient::default();
+/// let user: Option<User> = helix
+///     .get_user_from_login("justintv".to_string(), &token).await.unwrap();
+/// # Ok(()) }
+/// ```
 #[cfg(all(feature = "client"))]
 #[cfg_attr(nightly, doc(cfg(all(feature = "client", feature = "helix"))))]
 #[derive(Clone)]
@@ -659,6 +679,15 @@ where
     pub request: Option<R>,
 }
 
+impl<R, D, T> Response<R, D>
+where
+    R: Request<Response = D>,
+    D: IntoIterator<Item = T> + PartialEq + serde::de::DeserializeOwned,
+{
+    /// Get first result of this response.
+    pub fn first(self) -> Option<T> { self.data.into_iter().next() }
+}
+
 #[cfg(feature = "client")]
 impl<R, D> Response<R, D>
 where

src/lib.rs

@@ -44,6 +44,31 @@
 //! # }
 //! ```
 //!
+//! There is also a convenience function for accesssing channel information with a specified login name
+//!
+//! ```rust,no_run
+//! # use twitch_api2::{TwitchClient, helix::channels::GetChannelInformationRequest};
+//! # use twitch_oauth2::{AppAccessToken, Scope, TwitchToken, tokens::errors::TokenError};
+//!
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+//! # let surf_http_client = twitch_oauth2::dummy_http_client; // This is only here to fool doc tests
+//! # let client_id = twitch_oauth2::ClientId::new("validclientid".to_string());
+//! # let client_secret = twitch_oauth2::ClientSecret::new("validclientsecret".to_string());
+//! # let token =
+//! #   match AppAccessToken::get_app_access_token(surf_http_client, client_id, client_secret, Scope::all()).await {
+//! #       Ok(t) => t,
+//! #       Err(TokenError::Request(e)) => panic!("got error: {:?}", e),
+//! #       Err(e) => panic!(e),
+//! #   };
+//! let client = TwitchClient::new();
+//! # let _: &TwitchClient<twitch_api2::DummyHttpClient> = &client;
+//!
+//! println!("{:?}", &client.helix.get_channel_from_login("twitch".to_string(), &token).await?.unwrap().title);
+//! # Ok(())
+//! # }
+//! ```
+//!
 //! # Features
 //!
 //! This crate provides almost no functionality by default, only exposing [`types`]. To enable more features, refer to below table.