Merge pull request #47 from Sleitnick/feature/notifications

Notifications

Cargo.toml

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

README.md

@@ -31,7 +31,7 @@ Possible use-cases:
 | :x: | Instances |
 | :white_check_mark: | Subscriptions |
 | :x: | Inventory |
-| :x: | User Notifications |
+| :white_check_mark: | User Notifications |
 
 - :white_check_mark: = Supported
 - :x: = Not yet supported
@@ -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.9.0
+$ aftman add Sleitnick/rbxcloud@0.10.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.9.0"
+rbxcloud = "0.10.0"
 ```
 
 Alternatively, use `cargo add`.

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.9.0
+$ aftman add Sleitnick/rbxcloud@0.10.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.9.0" }
+rbxcloud = { github = "Sleitnick/rbxcloud", version = "0.10.0" }
 ```
 
 Next, run `foreman install` to install `rbxcloud`.

docs/cli/cli-notification.md

@@ -0,0 +1,21 @@
+# Notification API
+
+## Send Notification
+Send a notification to a user.
+```
+Usage: rbxcloud notification send [OPTIONS] --universe-id <UNIVERSE_ID> --user-id <USER_ID> --payload <PAYLOAD> --api-key <API_KEY>
+
+Options:
+  -u, --universe-id <UNIVERSE_ID>  Universe ID
+  -U, --user-id <USER_ID>          User ID
+  -P, --payload <PAYLOAD>          Payload
+  -p, --pretty                     Pretty-print the JSON response
+  -a, --api-key <API_KEY>          Roblox Open Cloud API Key [env: RBXCLOUD_API_KEY=]
+  -h, --help                       Print help
+```
+
+### Example
+For an example payload, see the [Roblox documentation](https://create.roblox.com/docs/cloud/reference/UserNotification#Create-User-Notification).
+```
+$ rbxcloud notification send -p -u 12345 -U 6789 -P PAYLOAD_JSON -a MY_KEY
+```

docs/cli/cli-subscription.md

@@ -2,7 +2,7 @@
 
 ## Getting Subscription Info
 ```
-Usage: rbxcloud.exe subscription get [OPTIONS] --universe-id <UNIVERSE_ID> --product <PRODUCT> --subscription <SUBSCRIPTION> --api-key <API_KEY>
+Usage: rbxcloud subscription get [OPTIONS] --universe-id <UNIVERSE_ID> --product <PRODUCT> --subscription <SUBSCRIPTION> --api-key <API_KEY>
 
 Options:
   -u, --universe-id <UNIVERSE_ID>    Universe ID

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.9.0"
+rbxcloud = "0.10.0"
 ```
 
 Alternatively, use `cargo add`.

examples/send-notification.rs

@@ -0,0 +1,66 @@
+use std::collections::HashMap;
+
+use rbxcloud::rbx::{
+    error::Error,
+    types::{RobloxUserId, UniverseId},
+    v2::{
+        notification::{
+            JoinExperience, Notification, NotificationPayload, NotificationResponse,
+            NotificationSource, NotificationType, Parameter,
+        },
+        Client,
+    },
+};
+
+async fn send_notification() -> Result<NotificationResponse, Error> {
+    // Inputs:
+    let api_key = "MY_API_KEY";
+    let message_id = "MY_MESSAGE_ID";
+    let universe_id = 9876543210;
+    let user_id = 308165;
+
+    let client = Client::new(api_key);
+    let notification_client = client.notification(UniverseId(universe_id));
+
+    let notification = Notification {
+        source: NotificationSource {
+            universe: format!("universe/{}", universe_id),
+        },
+        payload: NotificationPayload {
+            message_id: message_id.to_string(),
+            notification_type: NotificationType::TypeUnspecified,
+            join_experience: Some(JoinExperience {
+                launch_data: "Some launch data here".to_string(),
+            }),
+            analytics_data: Some(HashMap::from([(
+                "category".to_string(),
+                "Bronze egg hatched".to_string(),
+            )])),
+            parameters: Some(HashMap::from([(
+                "key".to_string(),
+                Parameter {
+                    string_value: Some("bronze egg".to_string()),
+                    int64_value: None,
+                },
+            )])),
+        },
+    };
+
+    notification_client
+        .send(RobloxUserId(user_id), notification)
+        .await
+}
+
+#[tokio::main]
+async fn main() {
+    let send_result = send_notification().await;
+
+    match send_result {
+        Ok(result) => {
+            println!("Notification sent: {:?}", result);
+        }
+        Err(e) => {
+            eprintln!("{e:?}");
+        }
+    }
+}

mkdocs.yml

@@ -15,6 +15,7 @@ nav:
     - OrderedDataStore: cli/cli-ordered-datastore.md
     - Group: cli/cli-group.md
     - Subscription: cli/cli-subscription.md
+    - Notification: cli/cli-notification.md
   - Rust Lib:
     - Install: lib/lib-install.md
 

src/cli/mod.rs

@@ -3,15 +3,16 @@ mod datastore_cli;
 mod experience_cli;
 mod group_cli;
 mod messaging_cli;
+mod notification_cli;
 mod ordered_datastore_cli;
 mod subscription_cli;
 
 use clap::{Parser, Subcommand};
 
 use self::{
     assets_cli::Assets, datastore_cli::DataStore, experience_cli::Experience, group_cli::Group,
-    messaging_cli::Messaging, ordered_datastore_cli::OrderedDataStore,
-    subscription_cli::Subscription,
+    messaging_cli::Messaging, notification_cli::Notification,
+    ordered_datastore_cli::OrderedDataStore, subscription_cli::Subscription,
 };
 
 #[derive(Debug, Parser)]
@@ -43,6 +44,9 @@ pub enum Command {
 
     /// Access the Roblox Subscription API
     Subscription(Subscription),
+
+    /// Access the Roblox Notification API
+    Notification(Notification),
 }
 
 impl Cli {
@@ -55,6 +59,7 @@ impl Cli {
             Command::OrderedDatastore(command) => command.run().await,
             Command::Group(command) => command.run().await,
             Command::Subscription(command) => command.run().await,
+            Command::Notification(command) => command.run().await,
         }
     }
 }

src/cli/notification_cli.rs

@@ -0,0 +1,74 @@
+use clap::{Args, Subcommand};
+use rbxcloud::rbx::{
+    types::{RobloxUserId, UniverseId},
+    v2::Client,
+};
+
+#[derive(Debug, Subcommand)]
+pub enum NotificationCommands {
+    /// Send a notification to a user
+    Send {
+        /// Universe ID
+        #[clap(short, long, value_parser)]
+        universe_id: u64,
+
+        /// User ID
+        #[clap(short = 'U', long, value_parser)]
+        user_id: u64,
+
+        /// Payload
+        #[clap(short = 'P', long, value_parser)]
+        payload: String,
+
+        /// 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,
+    },
+}
+
+#[derive(Debug, Args)]
+pub struct Notification {
+    #[clap(subcommand)]
+    command: NotificationCommands,
+}
+
+impl Notification {
+    pub async fn run(self) -> anyhow::Result<Option<String>> {
+        match self.command {
+            NotificationCommands::Send {
+                universe_id,
+                user_id,
+                payload,
+                pretty,
+                api_key,
+            } => {
+                let client = Client::new(&api_key);
+                let notification_client = client.notification(UniverseId(universe_id));
+
+                let notification = serde_json::from_str::<
+                    rbxcloud::rbx::v2::notification::Notification,
+                >(&payload)?;
+
+                let res = notification_client
+                    .send(RobloxUserId(user_id), notification)
+                    .await;
+
+                match res {
+                    Ok(subscription_info) => {
+                        let r = if pretty {
+                            serde_json::to_string_pretty(&subscription_info)?
+                        } else {
+                            serde_json::to_string(&subscription_info)?
+                        };
+                        Ok(Some(r))
+                    }
+                    Err(err) => Err(anyhow::anyhow!(err)),
+                }
+            }
+        }
+    }
+}

src/rbx/v2/mod.rs

@@ -8,15 +8,17 @@ use self::{
         ListGroupMembershipsParams, ListGroupMembershipsResponse, ListGroupRolesParams,
         ListGroupRolesResponse,
     },
+    notification::{Notification, NotificationParams, NotificationResponse},
     subscription::{GetSubscriptionParams, GetSubscriptionResponse, SubscriptionView},
 };
 pub mod group;
 pub(crate) mod http_err;
+pub mod notification;
 pub mod subscription;
 
 use crate::rbx::error::Error;
 
-use super::types::{GroupId, UniverseId};
+use super::types::{GroupId, RobloxUserId, UniverseId};
 
 /// Access into the Roblox Open Cloud APIs.
 ///
@@ -40,6 +42,11 @@ pub struct SubscriptionClient {
     pub api_key: String,
 }
 
+pub struct NotificationClient {
+    pub api_key: String,
+    pub universe_id: UniverseId,
+}
+
 impl GroupClient {
     pub async fn get_info(&self) -> Result<GetGroupResponse, Error> {
         group::get_group(&GetGroupParams {
@@ -107,6 +114,21 @@ impl SubscriptionClient {
     }
 }
 
+impl NotificationClient {
+    pub async fn send(
+        &self,
+        user_id: RobloxUserId,
+        notification: Notification,
+    ) -> Result<NotificationResponse, Error> {
+        notification::send_notification(&NotificationParams {
+            api_key: self.api_key.clone(),
+            user_id,
+            notification,
+        })
+        .await
+    }
+}
+
 impl Client {
     pub fn new(api_key: &str) -> Client {
         Client {
@@ -126,4 +148,11 @@ impl Client {
             api_key: self.api_key.clone(),
         }
     }
+
+    pub fn notification(&self, universe_id: UniverseId) -> NotificationClient {
+        NotificationClient {
+            api_key: self.api_key.clone(),
+            universe_id,
+        }
+    }
 }