twitch_oauth2/

scopes.rs

//! Module for all possible scopes in twitch.
pub mod validator;
pub use validator::Validator;

use serde_derive::{Deserialize, Serialize};
use std::borrow::Cow;

macro_rules! scope_impls {
    (@omit #[deprecated($depr:tt)] $i:ident) => {
        #[cfg(_internal_never)]
        Self::$i
    };
    (@omit $i:ident) => {
        Self::$i
    };

    ($($(#[cfg(($cfg:meta))])* $(#[deprecated($depr:meta)])? $i:ident,scope: $rename:literal, doc: $doc:literal);* $(;)? ) => {
        #[doc = "Scopes for twitch."]
        #[doc = ""]
        #[doc = "<https://dev.twitch.tv/docs/authentication/scopes/>"]
        #[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, Hash)]
        #[non_exhaustive]
        #[serde(from = "String")]
        #[serde(into = "String")]
        pub enum Scope {
            $(
                $(#[cfg($cfg)])*
                $(#[deprecated($depr)])*
                #[doc = $doc]
                #[doc = "\n\n"]
                #[doc = "`"]
                #[doc = $rename]
                #[doc = "`"]
                #[serde(rename = $rename)] // Is this even needed?
                $i,
            )*
            #[doc = "Other scope that is not implemented."]
            Other(Cow<'static, str>),
        }

        impl std::fmt::Display for Scope {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                #![allow(deprecated)]

                f.write_str(match self {
                    Scope::Other(s) => &s,
                    $(
                        $(#[cfg($cfg)])*
                        Scope::$i => $rename,
                    )*
                })
            }
        }

        impl Scope {
            #[doc = "Get a vec of all defined twitch [Scopes][Scope]."]
            #[doc = "\n\n"]
            #[doc = "Please note that this may not work for you, as some auth flows and \"apis\" don't accept all scopes"]
            pub fn all() -> Vec<Scope> {
                vec![
                    $(
                        scope_impls!(@omit $(#[deprecated($depr)])* $i),
                    )*
                ]
            }

            #[doc = "Get a slice of all defined twitch [Scopes][Scope]."]
            #[doc = "\n\n"]
            #[doc = "Please note that this may not work for you, as some auth flows and \"apis\" don't accept all scopes"]
            pub const fn all_slice() -> &'static [Scope] {
                &[
                    $(
                        scope_impls!(@omit $(#[deprecated($depr)])* $i),
                    )*
                ]
            }

            #[doc = "Get a description for the token"]
            pub const fn description(&self) -> &'static str {
                #![allow(deprecated)]

                match self {

                    $(
                        $(#[cfg($cfg)])*
                        Self::$i => $doc,
                    )*
                    _ => "unknown scope"
                }
            }

            #[doc = "Make a scope from a cow string"]
            pub fn parse<C>(s: C) -> Scope where C: Into<Cow<'static, str>> {
                #![allow(deprecated)]
                use std::borrow::Borrow;
                let s = s.into();
                match s.borrow() {

                    $(
                        $(#[cfg($cfg)])*
                        $rename => {Scope::$i}
                    )*,
                    _ => Scope::Other(s)
                }
            }

            /// Get the scope as a borrowed string.
            pub fn as_str(&self) -> &str {
                #![allow(deprecated)]
                match self {
                    $(
                        $(#[cfg($cfg)])*
                        Scope::$i => $rename,
                    )*
                    Self::Other(c) => c.as_ref()
                }
            }

            /// Get the scope as a static string slice.
            ///
            /// ## Panics
            ///
            /// This function panics if the scope can't be represented as a static string slice
            pub const fn as_static_str(&self) -> &'static str {
                #![allow(deprecated)]
                match self {
                    $(
                        $(#[cfg($cfg)])*
                        Scope::$i => $rename,
                    )*
                    Self::Other(Cow::Borrowed(s)) => s,
                    _ => panic!(),
                }
            }
        }
        #[test]
        #[cfg(test)]
        fn sorted() {
            // Deprecated items come at the end, ignore them.
            let n_deprecated = [$(
                $(stringify!($depr),)*
            )*].len();
            let slice = [$(
                $(#[cfg($cfg)])*
                $rename,
            )*];
            let n_scopes = slice.len();
            let slice = &slice[..(n_scopes - n_deprecated)];
            let mut slice_sorted = [$(
                $(#[cfg($cfg)])*
                $rename,
            )*];
            let slice_sorted = &mut slice_sorted[..(n_scopes - n_deprecated)];
            slice_sorted.sort();
            for (scope, sorted) in slice.iter().zip(slice_sorted.iter()) {
                assert_eq!(scope, sorted);
            }
            assert_eq!(slice, slice_sorted);
        }
    };
}

/*
Extract from the Twitch docs (https://dev.twitch.tv/docs/authentication/scopes/) by pasting in the DevTools:

copy(
  (() => {
    let tbl = $$("tbody")
      .map((tb) => [...tb.children])
      .flat()
      .map((tr) => [
        tr.children[0].textContent,
        tr.children[1].firstChild.textContent.trim(),
      ])
      .map(([name, desc]) => [
        name
          .split(/[:_-]/)
          .map((x) => x[0].toUpperCase() + x.slice(1))
          .join("") + ", ",
        'scope: "' + name + '", ',
        "doc: " + JSON.stringify(desc) + ";",
      ])
      .sort((a, b) => a[0] > b[0]);
    let [l0, l1] = tbl.reduce(
      (acc, cur) => [
        Math.max(acc[0], cur[0].length),
        Math.max(acc[1], cur[1].length),
      ],
      [0, 0],
    );
    return tbl
      .map(([a, b, c]) => `    ${a.padRight(l0, " ")}${b.padRight(l1, " ")}${c}`)
      .join("\n");
  })(),
);
*/

scope_impls!(
    AnalyticsReadExtensions,        scope: "analytics:read:extensions",         doc: "View analytics data for the Twitch Extensions owned by the authenticated account.";
    AnalyticsReadGames,             scope: "analytics:read:games",              doc: "View analytics data for the games owned by the authenticated account.";
    BitsRead,                       scope: "bits:read",                         doc: "View Bits information for a channel.";
    ChannelBot,                     scope: "channel:bot",                       doc: "Joins your channel’s chatroom as a bot user, and perform chat-related actions as that user.";
    ChannelEditCommercial,          scope: "channel:edit:commercial",           doc: "Run commercials on a channel.";
    ChannelManageAds,               scope: "channel:manage:ads",                doc: "Manage ads schedule on a channel.";
    ChannelManageBroadcast,         scope: "channel:manage:broadcast",          doc: "Manage a channel’s broadcast configuration, including updating channel configuration and managing stream markers and stream tags.";
    ChannelManageClips,             scope: "channel:manage:clips",              doc: "Manage Clips for a channel.";
    ChannelManageExtensions,        scope: "channel:manage:extensions",         doc: "Manage a channel’s Extension configuration, including activating Extensions.";
    ChannelManageGuestStar,         scope: "channel:manage:guest_star",         doc: "Manage Guest Star for your channel.";
    ChannelManageModerators,        scope: "channel:manage:moderators",         doc: "Add or remove the moderator role from users in your channel.";
    ChannelManagePolls,             scope: "channel:manage:polls",              doc: "Manage a channel’s polls.";
    ChannelManagePredictions,       scope: "channel:manage:predictions",        doc: "Manage of channel’s Channel Points Predictions";
    ChannelManageRaids,             scope: "channel:manage:raids",              doc: "Manage a channel raiding another channel.";
    ChannelManageRedemptions,       scope: "channel:manage:redemptions",        doc: "Manage Channel Points custom rewards and their redemptions on a channel.";
    ChannelManageSchedule,          scope: "channel:manage:schedule",           doc: "Manage a channel’s stream schedule.";
    ChannelManageVideos,            scope: "channel:manage:videos",             doc: "Manage a channel’s videos, including deleting videos.";
    ChannelManageVips,              scope: "channel:manage:vips",               doc: "Add or remove the VIP role from users in your channel.";
    ChannelModerate,                scope: "channel:moderate",                  doc: "Perform moderation actions in a channel.";
    ChannelReadAds,                 scope: "channel:read:ads",                  doc: "Read the ads schedule and details on your channel.";
    ChannelReadCharity,             scope: "channel:read:charity",              doc: "Read charity campaign details and user donations on your channel.";
    ChannelReadEditors,             scope: "channel:read:editors",              doc: "View a list of users with the editor role for a channel.";
    ChannelReadGoals,               scope: "channel:read:goals",                doc: "View Creator Goals for a channel.";
    ChannelReadGuestStar,           scope: "channel:read:guest_star",           doc: "Read Guest Star details for your channel.";
    ChannelReadHypeTrain,           scope: "channel:read:hype_train",           doc: "View Hype Train information for a channel.";
    ChannelReadPolls,               scope: "channel:read:polls",                doc: "View a channel’s polls.";
    ChannelReadPredictions,         scope: "channel:read:predictions",          doc: "View a channel’s Channel Points Predictions.";
    ChannelReadRedemptions,         scope: "channel:read:redemptions",          doc: "View Channel Points custom rewards and their redemptions on a channel.";
    ChannelReadStreamKey,           scope: "channel:read:stream_key",           doc: "View an authorized user’s stream key.";
    ChannelReadSubscriptions,       scope: "channel:read:subscriptions",        doc: "View a list of all subscribers to a channel and check if a user is subscribed to a channel.";
    ChannelReadVips,                scope: "channel:read:vips",                 doc: "Read the list of VIPs in your channel.";
    ChatEdit,                       scope: "chat:edit",                         doc: "Send chat messages to a chatroom using an IRC connection.";
    ChatRead,                       scope: "chat:read",                         doc: "View chat messages sent in a chatroom using an IRC connection.";
    ClipsEdit,                      scope: "clips:edit",                        doc: "Manage Clips for a channel.";
    EditorManageClips,              scope: "editor:manage:clips",               doc: "Manage Clips as an editor.";
    ModerationRead,                 scope: "moderation:read",                   doc: "View a channel’s moderation data including Moderators, Bans, Timeouts, and Automod settings.";
    ModeratorManageAnnouncements,   scope: "moderator:manage:announcements",    doc: "Send announcements in channels where you have the moderator role.";
    ModeratorManageAutoMod,         scope: "moderator:manage:automod",          doc: "Manage messages held for review by AutoMod in channels where you are a moderator.";
    ModeratorManageAutomodSettings, scope: "moderator:manage:automod_settings", doc: "Manage a broadcaster’s AutoMod settings.";
    ModeratorManageBannedUsers,     scope: "moderator:manage:banned_users",     doc: "Ban and unban users.";
    ModeratorManageBlockedTerms,    scope: "moderator:manage:blocked_terms",    doc: "Manage a broadcaster’s list of blocked terms.";
    ModeratorManageChatMessages,    scope: "moderator:manage:chat_messages",    doc: "Delete chat messages in channels where you have the moderator role";
    ModeratorManageChatSettings,    scope: "moderator:manage:chat_settings",    doc: "Manage a broadcaster’s chat room settings.";
    ModeratorManageGuestStar,       scope: "moderator:manage:guest_star",       doc: "Manage Guest Star for channels where you are a Guest Star moderator.";
    ModeratorManageShieldMode,      scope: "moderator:manage:shield_mode",      doc: "Manage a broadcaster’s Shield Mode status.";
    ModeratorManageShoutouts,       scope: "moderator:manage:shoutouts",        doc: "Manage a broadcaster’s shoutouts.";
    ModeratorManageSuspiciousUsers, scope: "moderator:manage:suspicious_users", doc: "Manage suspicious user statuses in channels where the user has the moderator role.";
    ModeratorManageUnbanRequests,   scope: "moderator:manage:unban_requests",   doc: "Manage a broadcaster’s unban requests.";
    ModeratorManageWarnings,        scope: "moderator:manage:warnings",         doc: "Warn users in channels where you have the moderator role.";
    ModeratorReadAutomodSettings,   scope: "moderator:read:automod_settings",   doc: "View a broadcaster’s AutoMod settings.";
    ModeratorReadBannedUsers,       scope: "moderator:read:banned_users",       doc: "Read the list of bans or unbans in channels where you have the moderator role.";
    ModeratorReadBlockedTerms,      scope: "moderator:read:blocked_terms",      doc: "View a broadcaster’s list of blocked terms.";
    ModeratorReadChatMessages,      scope: "moderator:read:chat_messages",      doc: "Read deleted chat messages in channels where you have the moderator role.";
    ModeratorReadChatSettings,      scope: "moderator:read:chat_settings",      doc: "View a broadcaster’s chat room settings.";
    ModeratorReadChatters,          scope: "moderator:read:chatters",           doc: "View the chatters in a broadcaster’s chat room.";
    ModeratorReadFollowers,         scope: "moderator:read:followers",          doc: "Read the followers of a broadcaster.";
    ModeratorReadGuestStar,         scope: "moderator:read:guest_star",         doc: "Read Guest Star details for channels where you are a Guest Star moderator.";
    ModeratorReadModerators,        scope: "moderator:read:moderators",         doc: "Read the list of moderators in channels where you have the moderator role.";
    ModeratorReadShieldMode,        scope: "moderator:read:shield_mode",        doc: "View a broadcaster’s Shield Mode status.";
    ModeratorReadShoutouts,         scope: "moderator:read:shoutouts",          doc: "View a broadcaster’s shoutouts.";
    ModeratorReadSuspiciousUsers,   scope: "moderator:read:suspicious_users",   doc: "Read chat messages from suspicious users and see users flagged as suspicious in channels where the user has the moderator role.";
    ModeratorReadUnbanRequests,     scope: "moderator:read:unban_requests",     doc: "View a broadcaster’s unban requests.";
    ModeratorReadVips,              scope: "moderator:read:vips",               doc: "Read the list of VIPs in channels where you have the moderator role.";
    ModeratorReadWarnings,          scope: "moderator:read:warnings",           doc: "Read warnings in channels where you have the moderator role.";
    UserBot,                        scope: "user:bot",                          doc: "Join a specified chat channel as your user and appear as a bot, and perform chat-related actions as your user.";
    UserEdit,                       scope: "user:edit",                         doc: "Manage a user object.";
    UserEditBroadcast,              scope: "user:edit:broadcast",               doc: "View and edit a user’s broadcasting configuration, including Extension configurations.";
    UserManageBlockedUsers,         scope: "user:manage:blocked_users",         doc: "Manage the block list of a user.";
    UserManageChatColor,            scope: "user:manage:chat_color",            doc: "Update the color used for the user’s name in chat.";
    UserManageWhispers,             scope: "user:manage:whispers",              doc: "Receive whispers sent to your user, and send whispers on your user’s behalf.";
    UserReadBlockedUsers,           scope: "user:read:blocked_users",           doc: "View the block list of a user.";
    UserReadBroadcast,              scope: "user:read:broadcast",               doc: "View a user’s broadcasting configuration, including Extension configurations.";
    UserReadChat,                   scope: "user:read:chat",                    doc: "Receive chatroom messages and informational notifications relating to a channel’s chatroom.";
    UserReadEmail,                  scope: "user:read:email",                   doc: "View a user’s email address.";
    UserReadEmotes,                 scope: "user:read:emotes",                  doc: "View emotes available to a user";
    UserReadFollows,                scope: "user:read:follows",                 doc: "View the list of channels a user follows.";
    UserReadModeratedChannels,      scope: "user:read:moderated_channels",      doc: "Read the list of channels you have moderator privileges in.";
    UserReadSubscriptions,          scope: "user:read:subscriptions",           doc: "View if an authorized user is subscribed to specific channels.";
    UserReadWhispers,               scope: "user:read:whispers",                doc: "Receive whispers sent to your user.";
    UserWriteChat,                  scope: "user:write:chat",                   doc: "Send chat messages to a chatroom.";
    WhispersRead,                   scope: "whispers:read",                     doc: "Receive whisper messages for your user using PubSub.";

    // Deprecated/removed scopes:

    #[deprecated(note = "Use `ChannelReadSubscriptions` (`channel:read:subscriptions`) instead")]
    ChannelSubscriptions,           scope: "channel_subscriptions",             doc: "Read all subscribers to your channel.";
    #[deprecated(note = "Not used anymore, see https://discuss.dev.twitch.tv/t/deprecation-of-create-and-delete-follows-api-endpoints/32351")]
    UserEditFollows,                scope: "user:edit:follows",                 doc: "\\[DEPRECATED\\] Was previously used for “Create User Follows” and “Delete User Follows.";
    #[deprecated(note = "Use `UserManageWhispers` (`user:manage:whispers`) instead")]
    WhispersEdit,                   scope: "whispers:edit",                     doc: "\\[DEPRECATED\\] Send whisper messages.";
);

impl Scope {
    /// Get the scope as a [validator](Validator).
    pub const fn to_validator(self) -> Validator { Validator::scope(self) }
}

impl std::borrow::Borrow<str> for Scope {
    fn borrow(&self) -> &str { self.as_str() }
}

impl From<String> for Scope {
    fn from(s: String) -> Self { Scope::parse(s) }
}

impl From<Scope> for String {
    fn from(s: Scope) -> Self { s.to_string() }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn custom_scope() {
        assert_eq!(
            Scope::Other(Cow::from("custom_scope")),
            Scope::parse("custom_scope")
        )
    }

    #[test]
    fn roundabout() {
        for scope in Scope::all() {
            assert_eq!(scope, Scope::parse(scope.to_string()))
        }
    }

    #[test]
    #[allow(deprecated)]
    fn no_deprecated() {
        for scope in Scope::all() {
            assert!(scope != Scope::ChannelSubscriptions)
        }
    }
}