add more readmes and fix example

Author: Emilgardis

CONTRIBUTING.md

@@ -1,3 +1,20 @@
+### Fetching the git submodules
+
+To get started with using this repository, ensure you have initialized and updated the submodules in order to retrieve their contents.
+
+```sh
+git submodule update --init --recursive
+```
+
+alternatively, you can also run
+
+```sh
+git submodule init
+git submodule update
+```
+
+### Maintaining
+
 #### Updating twitch_oauth2
 
 To update the `twitch_oauth2` submodule, run the appropriate

README.md

@@ -12,7 +12,7 @@ See [documentation](https://docs.rs/twitch_api) for more info.
 You can see current unpublished docs for the main branch here: [![local-docs]](https://twitch-rs.github.io/twitch_api/twitch_api)
 
 See [examples](./examples) for examples. If you want to run them locally,
-make sure you fetch the git submodules first.
+make sure you [get the git submodules](./CONTRIBUTING.md#fetching-the-git-submodules) first.
 
 [local-docs]: https://img.shields.io/github/actions/workflow/status/twitch-rs/twitch_api/gh-pages.yml?label=dev%20docs&style=flat-square&event=push
 

examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+## Getting a token
+
+To run the examples, you will need to have a Twitch OAuth token. You can get one by following the [Twitch OAuth guide](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth).
+
+There are sites available that can help you generate these tokens, or you can use the official [Twitch CLI](https://github.com/twitchdev/twitch-cli), `twitch_oauth2::UserToken::builder()` or `twitch_oauth2::tokens::ImplicitUserTokenBuilder`
+
+## Running the examples
+
+To run an example, ensure you've gotten the [submodules](../CONTRIBUTING.md#fetching-the-git-submodules) and have a [token](#getting-a-token) available.
+
+```sh
+git clone https://github.com/twitch-rs/twitch_api.git --recurse-submodules
+cd twitch_api
+# if you didn't get the submodules, run
+# git submodule update --init --recursive
+cargo run --example <example_name> -- <token>
+```
+
+Some examples are their own crates/workspace members, you can run these with
+
+```sh
+cargo run -p <example> -- <args>
+```
+
+## .env
+
+Instead of passing a token to every example, you can also create a `.env` file in the root of the repository with the following contents
+
+```txt
+# .env
+TWITCH_TOKEN=mytoken
+CLIENT_ID=myclientid
+CLIENT_SECRET=myclientid
+```

examples/eventsub_websocket/README.md

@@ -0,0 +1,13 @@
+# EventSub Websocket Example
+
+This example shows how to use the EventSub websocket to listen to events.
+
+Ensure you've [gotten the git submodules](../../CONTRIBUTING.md#fetching-the-git-submodules) to [run this example](../README.md#running-the-examples)
+
+```sh
+git clone https://github.com/twitch-rs/twitch_api.git --recurse-submodules
+cd twitch_api
+# if you didn't get the submodules, run
+# git submodule update --init --recursive
+cargo run -p eventsub_websocket -- --access-token <token>
+```

examples/eventsub_websocket/src/main.rs

@@ -5,15 +5,13 @@ pub mod websocket;
 
 use clap::Parser;
 pub use opts::Secret;
-use twitch_oauth2::UserToken;
 
 use std::sync::Arc;
 
 use opts::Opts;
 
 use eyre::Context;
 
-use tokio::sync::RwLock;
 use twitch_api::{client::ClientDefault, HelixClient};
 
 #[tokio::main]
@@ -52,7 +50,8 @@ pub async fn run(opts: Arc<Opts>) -> eyre::Result<()> {
     );
 
     // Get the access token from the cli, dotenv or an oauth service
-    let token = util::get_access_token(client.get_client(), &opts).await?;
+    let token: twitch_oauth2::UserToken =
+        util::get_access_token(client.get_client(), &opts).await?;
 
     // Get the user id of the channel we want to listen to
     let user_id = if let Some(ref id) = opts.channel_id {

examples/eventsub_websocket/src/opts.rs

@@ -3,12 +3,12 @@ use clap::{builder::ArgPredicate, ArgGroup, Parser};
 #[derive(Parser, Debug, Clone)]
 #[clap(about, version,
     group = ArgGroup::new("token").multiple(false).required(false),
-    group = ArgGroup::new("service").multiple(true).requires("oauth2-service-url"),
+    group = ArgGroup::new("service").multiple(true).requires("oauth2_service_url"),
     group = ArgGroup::new("channel").multiple(true).required(false),
 )]
 pub struct Opts {
     /// OAuth2 Access token
-    #[clap(long, env, hide_env = true, group = "token", value_parser = is_token, required_unless_present = "service"
+    #[clap(long, env, hide_env = true, group = "token", value_parser = to_token, required_unless_present = "service"
     )]
     pub access_token: Option<Secret>,
     /// Name of channel to monitor. If left out, defaults to owner of access token.
@@ -20,7 +20,7 @@ pub struct Opts {
     /// URL to service that provides OAuth2 token. Called on start and whenever the token needs to be refreshed.
     ///
     /// This application does not do any refreshing of tokens.
-    #[clap(long, env, hide_env = true, group = "token",
+    #[clap(long, env, hide_env = true, group = "service",
         value_parser = url::Url::parse, required_unless_present = "token"
         )]
     pub oauth2_service_url: Option<url::Url>,
@@ -47,14 +47,14 @@ pub struct Opts {
     pub oauth2_service_refresh: Option<u64>,
 }
 
-pub fn is_token(s: &str) -> eyre::Result<()> {
+pub fn to_token(s: &str) -> eyre::Result<Secret> {
     if s.starts_with("oauth:") {
         eyre::bail!("token should not have `oauth:` as a prefix")
     }
     if s.len() != 30 {
         eyre::bail!("token needs to be 30 characters long")
     }
-    Ok(())
+    Ok(Secret(s.to_owned()))
 }
 
 #[derive(Clone)]

examples/tower_client/src/main.rs

@@ -21,6 +21,7 @@ fn main() {
 }
 
 #[tokio::main]
+/// Run the application
 async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
     let _ = dotenvy::dotenv();
     tracing_subscriber::fmt()
@@ -53,11 +54,12 @@ async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>>
         .service(
             hyper::Client::builder().build::<_, hyper::Body>(hyper_tls::HttpsConnector::new()),
         );
+
     tracing::info!("Creating client");
     let client: HelixClient<Box<dyn twitch_api::HttpClient<Error = _>>> =
         HelixClient::with_client(Box::new(TowerService::new(tower_client)));
-    tracing::info!("Getting token");
 
+    tracing::info!("Getting token");
     let token = UserToken::from_existing(
         &client,
         std::env::var("TWITCH_TOKEN")

examples/twitch_oauth2-integration/src/lib.rs

@@ -7,6 +7,7 @@ pub async fn get_auth_token_request(
     let client_secret = ClientSecret::from("aaaa");
 
     let token =
+            // here we can use the TwitchClient as a client for twitch_oauth2
         AppAccessToken::get_app_access_token(client, client_id, client_secret, Scope::all())
             .await
             .unwrap();

src/lib.rs

@@ -17,31 +17,35 @@
 //! Get information about a channel with the [`Get Channel Information`](crate::helix::channels::get_channel_information) helix endpoint.
 //!
 //! ```rust,no_run
+//! use twitch_api::twitch_oauth2::{
+//!     tokens::errors::AppAccessTokenError, AppAccessToken, TwitchToken,
+//! };
 //! use twitch_api::{helix::channels::GetChannelInformationRequest, TwitchClient};
-//! use twitch_api::twitch_oauth2::{tokens::errors::AppAccessTokenError, AppAccessToken, Scope, TwitchToken};
-//! # pub mod reqwest {pub type Client = twitch_api::client::DummyHttpClient;}
-//!
-//! # #[tokio::main]
-//! # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
-//! # let client_id = twitch_oauth2::ClientId::from("validclientid");
-//! # let client_secret = twitch_oauth2::ClientSecret::from("validclientsecret");
-//!
-//! let client: TwitchClient<reqwest::Client> = TwitchClient::default();
-//! let token =
-//!     AppAccessToken::get_app_access_token(&client, client_id, client_secret, Scope::all())
-//!         .await?;
-//! let ids: &[&twitch_types::UserIdRef] = &["27620241".into()];
-//! let req = GetChannelInformationRequest::broadcaster_ids(ids);
-//! println!(
-//!     "{:?}",
-//!     &client.helix.req_get(req, &token).await?.data[0].title
-//! );
-//! # Ok(())
+//! # pub mod reqwest {
+//! #     pub type Client = twitch_api::client::DummyHttpClient;
 //! # }
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+//!     let client: TwitchClient<reqwest::Client> = TwitchClient::default();
+//!     let token = AppAccessToken::get_app_access_token(
+//!         &client,
+//!         "validclientid".into(),
+//!         "validclientsecret".into(),
+//!         vec![/* scopes */],
+//!     )
+//!     .await?;
+//!     let ids: &[&twitch_types::UserIdRef] = &["27620241".into()];
+//!     let req = GetChannelInformationRequest::broadcaster_ids(ids);
+//!     println!(
+//!         "{:?}",
+//!         &client.helix.req_get(req, &token).await?.data[0].title
+//!     );
+//!     Ok(())
+//! }
 //! ```
 //!
 //! There is also convenience functions, like accessing channel information with a specified login name
-//!
 //! ```rust,no_run
 //! # use twitch_api::{TwitchClient, helix::channels::GetChannelInformationRequest};
 //! # use twitch_api::twitch_oauth2::{AppAccessToken, Scope, TwitchToken, tokens::errors::AppAccessTokenError};