Merge pull request #45 from Sleitnick/feature/v2-groups

v2 Groups

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rbxcloud"
-version = "0.7.0"
+version = "0.8.0"
 description = "CLI and SDK for the Roblox Open Cloud APIs"
 authors = ["Stephen Leitnick"]
 license = "MIT"

README.md

@@ -25,7 +25,7 @@ Possible use-cases:
 
 | | API v2 (Beta) |
 | -- | -- |
-| :x: | Groups |
+| :white_check_mark: | Groups |
 | :x: | Universes |
 | :x: | Places |
 | :x: | Instances |
@@ -42,7 +42,7 @@ The goal of this project is to support all API endpoints that Roblox provides.
 ### Aftman
 Run the `aftman add` command within your project directory. This will add `rbxcloud` to the project's `aftman.toml` file (or create one if it doesn't yet exist).
 ```sh
-$ aftman add Sleitnick/rbxcloud@0.7.0
+$ aftman add Sleitnick/rbxcloud@0.8.0
 ```
 
 ### From Release
@@ -59,7 +59,7 @@ The library built for the CLI tool is available to use directly in Rust projects
 To use `rbxcloud` in a Rust project, simply add `rbxcloud` to the `Cargo.toml` dependency list.
 ```toml
 [dependencies]
-rbxcloud = "0.7.0"
+rbxcloud = "0.8.0"
 ```
 
 Alternatively, use `cargo add`.

docs/cli/cli-group.md

@@ -0,0 +1,61 @@
+# Group API
+
+## Get Group Info
+Get information about a group.
+```
+Usage: rbxcloud group get [OPTIONS] --group-id <GROUP_ID> --api-key <API_KEY>
+
+Options:
+  -a, --api-key <API_KEY>    Roblox Open Cloud API Key [env: RBXCLOUD_API_KEY=]
+  -g, --group-id <GROUP_ID>  Group ID
+  -p, --pretty               Pretty-print the JSON response
+  -h, --help                 Print help
+```
+
+### Example
+```
+$ rbxcloud group get -p -g 12345 -a MY_KEY
+```
+
+## Get Group Shout
+Get a group's current shout and its metadata.
+```
+Usage: rbxcloud group shout [OPTIONS] --group-id <GROUP_ID> --api-key <API_KEY>
+
+Options:
+  -a, --api-key <API_KEY>    Roblox Open Cloud API Key [env: RBXCLOUD_API_KEY=]
+  -g, --group-id <GROUP_ID>  Group ID
+  -p, --pretty               Pretty-print the JSON response
+  -o, --only-message         Only return the shout message string
+  -h, --help                 Print help
+```
+
+### Example
+Get a group's shout and its metadata:
+```
+$ rbxcloud group shout -p -g 12345 -a MY_KEY
+```
+
+Get a group's shout message only:
+```
+$ rbxcloud group shout -p -g 12345 -a MY_KEY --only-message
+```
+
+## List Group Roles
+List the roles of a given group.
+```
+Usage: rbxcloud group roles [OPTIONS] --group-id <GROUP_ID> --api-key <API_KEY>
+
+Options:
+  -g, --group-id <GROUP_ID>                Group ID
+  -p, --pretty                             Pretty-print the JSON response
+  -m, --max-page-size <MAX_PAGE_SIZE>      Max items returned per page
+  -n, --next-page-token <NEXT_PAGE_TOKEN>  Next page token
+  -a, --api-key <API_KEY>                  Roblox Open Cloud API Key [env: RBXCLOUD_API_KEY=]
+  -h, --help                               Print help
+```
+
+### Example
+```
+$ rbxcloud group roles -p -g 12345 -a MY_KEY
+```

docs/cli/cli-install.md

@@ -7,7 +7,7 @@ There are a few different ways to install the `rbxcloud` CLI.
 ### [Aftman](https://github.com/LPGhatguy/aftman) <small>(Preferred)</small>
 Run the `aftman add` command within your project directory. This will add `rbxcloud` to the project's `aftman.toml` file (or create one if it doesn't yet exist).
 ```sh
-$ aftman add Sleitnick/rbxcloud@0.7.0
+$ aftman add Sleitnick/rbxcloud@0.8.0
 ```
 
 Next, run `aftman install` to install `rbxcloud`.
@@ -17,7 +17,7 @@ Add `rbxcloud` under the `[tools]` section of your `foreman.toml` file.
 ```toml
 # foreman.toml
 [tools]
-rbxcloud = { github = "Sleitnick/rbxcloud", version = "0.7.0" }
+rbxcloud = { github = "Sleitnick/rbxcloud", version = "0.8.0" }
 ```
 
 Next, run `foreman install` to install `rbxcloud`.

docs/lib/lib-install.md

@@ -5,7 +5,7 @@
 To use `rbxcloud` in a Rust project, simply add `rbxcloud` to the `Cargo.toml` dependency list.
 ```toml
 [dependencies]
-rbxcloud = "0.7.0"
+rbxcloud = "0.8.0"
 ```
 
 Alternatively, use `cargo add`.

examples/group-get-shout.rs

@@ -0,0 +1,25 @@
+use rbxcloud::rbx::{
+    error::Error,
+    v2::{group::GroupId, Client},
+};
+
+async fn get_group_shout() -> Result<String, Error> {
+    // Inputs:
+    let api_key = "MY_API_KEY";
+    let group_id = 9876543210;
+
+    let client = Client::new(api_key);
+    let group = client.group(GroupId(group_id));
+
+    // Get the shout's content:
+    group.get_shout().await.map(|r| r.content)
+}
+
+#[tokio::main]
+async fn main() {
+    let shout_res = get_group_shout().await;
+    match shout_res {
+        Ok(shout) => println!("{shout}"),
+        Err(e) => eprintln!("{e:?}"),
+    }
+}

src/cli/group_cli.rs

@@ -0,0 +1,196 @@
+use clap::{Args, Subcommand};
+use rbxcloud::rbx::v2::{group::GroupId, Client};
+
+#[derive(Debug, Subcommand)]
+pub enum GroupCommands {
+    /// Get info about the group
+    Get {
+        /// Group ID
+        #[clap(short, long, value_parser)]
+        group_id: u64,
+
+        /// Pretty-print the JSON response
+        #[clap(short, long, value_parser, default_value_t = false)]
+        pretty: bool,
+
+        /// Roblox Open Cloud API Key
+        #[clap(short, long, value_parser, env = "RBXCLOUD_API_KEY")]
+        api_key: String,
+    },
+
+    /// Get the current shout and other metadata
+    Shout {
+        /// Group ID
+        #[clap(short, long, value_parser)]
+        group_id: u64,
+
+        /// Pretty-print the JSON response
+        #[clap(short, long, value_parser, default_value_t = false)]
+        pretty: bool,
+
+        /// Only return the shout message string
+        #[clap(short, long, value_parser, default_value_t = false)]
+        only_message: bool,
+
+        /// Roblox Open Cloud API Key
+        #[clap(short, long, value_parser, env = "RBXCLOUD_API_KEY")]
+        api_key: String,
+    },
+
+    /// List the roles of a group
+    Roles {
+        /// Group ID
+        #[clap(short, long, value_parser)]
+        group_id: u64,
+
+        /// Pretty-print the JSON response
+        #[clap(short, long, value_parser, default_value_t = false)]
+        pretty: bool,
+
+        /// Max items returned per page
+        #[clap(short, long, value_parser)]
+        max_page_size: Option<u32>,
+
+        /// Next page token
+        #[clap(short, long, value_parser)]
+        next_page_token: Option<String>,
+
+        /// Roblox Open Cloud API Key
+        #[clap(short, long, value_parser, env = "RBXCLOUD_API_KEY")]
+        api_key: String,
+    },
+
+    /// List the memberships of a group
+    Memberships {
+        /// Group ID
+        #[clap(short, long, value_parser)]
+        group_id: u64,
+
+        /// Pretty-print the JSON response
+        #[clap(short, long, value_parser, default_value_t = false)]
+        pretty: bool,
+
+        /// Max items returned per page
+        #[clap(short, long, value_parser)]
+        max_page_size: Option<u32>,
+
+        /// Filter
+        #[clap(short, long, value_parser)]
+        filter: Option<String>,
+
+        /// Next page token
+        #[clap(short, long, value_parser)]
+        next_page_token: Option<String>,
+
+        /// Roblox Open Cloud API Key
+        #[clap(short, long, value_parser, env = "RBXCLOUD_API_KEY")]
+        api_key: String,
+    },
+}
+
+#[derive(Debug, Args)]
+pub struct Group {
+    #[clap(subcommand)]
+    command: GroupCommands,
+}
+
+impl Group {
+    pub async fn run(self) -> anyhow::Result<Option<String>> {
+        match self.command {
+            GroupCommands::Get {
+                group_id,
+                api_key,
+                pretty,
+            } => {
+                let client = Client::new(&api_key);
+                let group = client.group(GroupId(group_id));
+                let res = group.get_info().await;
+                match res {
+                    Ok(group_info) => {
+                        let r = if pretty {
+                            serde_json::to_string_pretty(&group_info)?
+                        } else {
+                            serde_json::to_string(&group_info)?
+                        };
+                        Ok(Some(r))
+                    }
+                    Err(err) => Err(anyhow::anyhow!(err)),
+                }
+            }
+
+            GroupCommands::Shout {
+                group_id,
+                pretty,
+                only_message,
+                api_key,
+            } => {
+                let client = Client::new(&api_key);
+                let group = client.group(GroupId(group_id));
+                let res = group.get_shout().await;
+                match res {
+                    Ok(group_info) => {
+                        if only_message {
+                            return Ok(Some(group_info.content));
+                        }
+                        let r = if pretty {
+                            serde_json::to_string_pretty(&group_info)?
+                        } else {
+                            serde_json::to_string(&group_info)?
+                        };
+                        Ok(Some(r))
+                    }
+                    Err(err) => Err(anyhow::anyhow!(err)),
+                }
+            }
+
+            GroupCommands::Roles {
+                group_id,
+                api_key,
+                pretty,
+                max_page_size,
+                next_page_token,
+            } => {
+                let client = Client::new(&api_key);
+                let group = client.group(GroupId(group_id));
+                let res = group.list_roles(max_page_size, next_page_token).await;
+                match res {
+                    Ok(group_info) => {
+                        let r = if pretty {
+                            serde_json::to_string_pretty(&group_info)?
+                        } else {
+                            serde_json::to_string(&group_info)?
+                        };
+                        Ok(Some(r))
+                    }
+                    Err(err) => Err(anyhow::anyhow!(err)),
+                }
+            }
+
+            GroupCommands::Memberships {
+                group_id,
+                api_key,
+                pretty,
+                max_page_size,
+                next_page_token,
+                filter,
+            } => {
+                let client = Client::new(&api_key);
+                let group = client.group(GroupId(group_id));
+                let res = group
+                    .list_memberships(max_page_size, filter, next_page_token)
+                    .await;
+                match res {
+                    Ok(group_info) => {
+                        let r = if pretty {
+                            serde_json::to_string_pretty(&group_info)?
+                        } else {
+                            serde_json::to_string(&group_info)?
+                        };
+                        Ok(Some(r))
+                    }
+                    Err(err) => Err(anyhow::anyhow!(err)),
+                }
+            }
+        }
+    }
+}

src/cli/mod.rs

@@ -1,13 +1,14 @@
 mod assets_cli;
 mod datastore_cli;
 mod experience_cli;
+mod group_cli;
 mod messaging_cli;
 mod ordered_datastore_cli;
 
 use clap::{Parser, Subcommand};
 
 use self::{
-    assets_cli::Assets, datastore_cli::DataStore, experience_cli::Experience,
+    assets_cli::Assets, datastore_cli::DataStore, experience_cli::Experience, group_cli::Group,
     messaging_cli::Messaging, ordered_datastore_cli::OrderedDataStore,
 };
 
@@ -34,6 +35,9 @@ pub enum Command {
 
     /// Access the Roblox OrderedDataStore API
     OrderedDatastore(OrderedDataStore),
+
+    /// Access the Roblox Group API
+    Group(Group),
 }
 
 impl Cli {
@@ -44,6 +48,7 @@ impl Cli {
             Command::Messaging(command) => command.run().await,
             Command::Datastore(command) => command.run().await,
             Command::OrderedDatastore(command) => command.run().await,
+            Command::Group(command) => command.run().await,
         }
     }
 }

src/rbx/mod.rs

@@ -4,3 +4,4 @@
 pub mod error;
 pub(crate) mod util;
 pub mod v1;
+pub mod v2;