feat(widgets): add widgets (#167)

Author: DanielleHuisman

src/lib.rs

@@ -15,6 +15,7 @@ pub mod portal;
 pub mod roles;
 pub mod sso;
 pub mod user_management;
+pub mod widgets;
 
 pub use crate::core::*;
 pub use crate::workos::*;

src/portal.rs

@@ -18,7 +18,7 @@ pub struct Portal<'a> {
 }
 
 impl<'a> Portal<'a> {
-    /// Returns a new [`AdminPortal`] instance for the provided WorkOS client.
+    /// Returns a new [`Portal`] instance for the provided WorkOS client.
     pub fn new(workos: &'a WorkOs) -> Self {
         Self { workos }
     }

src/widgets.rs

@@ -0,0 +1,23 @@
+//! A module for interacting with the WorkOS Widgets API.
+//!
+//! [WorkOS Docs: Widgets Guide](https://workos.com/docs/authkit/widgets)
+
+mod operations;
+
+pub use operations::*;
+
+use crate::WorkOs;
+
+/// Widgets.
+///
+/// [WorkOS Docs: Widgets Guide](https://workos.com/docs/authkit/widgets)
+pub struct Widgets<'a> {
+    workos: &'a WorkOs,
+}
+
+impl<'a> Widgets<'a> {
+    /// Returns a new [`Widget`] instance for the provided WorkOS client.
+    pub fn new(workos: &'a WorkOs) -> Self {
+        Self { workos }
+    }
+}

src/widgets/operations.rs

@@ -0,0 +1,3 @@
+mod generate_token;
+
+pub use generate_token::*;

src/widgets/operations/generate_token.rs

@@ -0,0 +1,160 @@
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+use crate::organizations::OrganizationId;
+use crate::user_management::UserId;
+use crate::widgets::Widgets;
+use crate::{ResponseExt, WorkOsResult};
+
+/// The scope of a widget token.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum WidgetTokenScope {
+    /// Manage users.
+    #[serde(rename = "widgets:users-table:manage")]
+    ManageUsers,
+
+    /// Manage SSO.
+    #[serde(rename = "widgets:sso:manage")]
+    ManageSso,
+
+    /// Manage domain verification.
+    #[serde(rename = "widgets:domain-verification:manage")]
+    ManageDomainVerification,
+}
+
+/// The parameters for [`GenerateToken`].
+#[derive(Debug, Serialize)]
+pub struct GenerateTokenParams<'a> {
+    /// An Organization identifier.
+    pub organization_id: &'a OrganizationId,
+
+    /// A User identifier.
+    pub user_id: Option<&'a UserId>,
+
+    /// Scopes to include in the widget token.
+    pub scopes: Option<Vec<WidgetTokenScope>>,
+}
+
+/// The response for [`GenerateToken`].
+#[derive(Debug, Deserialize)]
+pub struct GenerateTokenResponse {
+    /// An ephemeral token to access WorkOS widgets.
+    pub token: String,
+}
+
+/// An error returned from [`GenerateToken`].
+#[derive(Debug)]
+pub enum GenerateTokenError {}
+
+/// [WorkOS Docs: Generate a Widget token](https://workos.com/docs/reference/widgets/get-token)
+#[async_trait]
+pub trait GenerateToken {
+    /// Generate a widget token scoped to an organization and user with the specified scopes.
+    ///
+    /// [WorkOS Docs: Generate a Widget token](https://workos.com/docs/reference/widgets/get-token)
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use workos::WorkOsResult;
+    /// # use workos::organizations::OrganizationId;
+    /// # use workos::user_management::UserId;
+    /// # use workos::widgets::*;
+    /// use workos::{ApiKey, WorkOs};
+    ///
+    /// # async fn run() -> WorkOsResult<(), GenerateTokenError> {
+    /// let workos = WorkOs::new(&ApiKey::from("sk_example_123456789"));
+    ///
+    /// let GenerateTokenResponse { token } = workos
+    ///     .widgets()
+    ///     .generate_token(&GenerateTokenParams {
+    ///         organization_id: &OrganizationId::from("org_01EHZNVPK3SFK441A1RGBFSHRT"),
+    ///         user_id: Some(&UserId::from("usr_01EHZNVPK3SFK441A1RGBFSHRT")),
+    ///         scopes: Some(vec![WidgetTokenScope::ManageUsers]),
+    ///     })
+    ///     .await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    async fn generate_token(
+        &self,
+        params: &GenerateTokenParams<'_>,
+    ) -> WorkOsResult<GenerateTokenResponse, GenerateTokenError>;
+}
+
+#[async_trait]
+impl GenerateToken for Widgets<'_> {
+    async fn generate_token(
+        &self,
+        params: &GenerateTokenParams<'_>,
+    ) -> WorkOsResult<GenerateTokenResponse, GenerateTokenError> {
+        let url = self.workos.base_url().join("/widgets/token")?;
+
+        let response = self
+            .workos
+            .client()
+            .post(url)
+            .bearer_auth(self.workos.key())
+            .json(&params)
+            .send()
+            .await?
+            .handle_unauthorized_or_generic_error()
+            .await?
+            .json::<GenerateTokenResponse>()
+            .await?;
+
+        Ok(response)
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use mockito::Matcher;
+    use serde_json::json;
+    use tokio;
+
+    use crate::organizations::OrganizationId;
+    use crate::{ApiKey, WorkOs};
+
+    use super::*;
+
+    #[tokio::test]
+    async fn it_calls_the_generate_token_endpoint() {
+        let mut server = mockito::Server::new_async().await;
+
+        let workos = WorkOs::builder(&ApiKey::from("sk_example_123456789"))
+            .base_url(&dbg!(server.url()))
+            .unwrap()
+            .build();
+
+        server
+            .mock("POST", "/widgets/token")
+            .match_header("Authorization", "Bearer sk_example_123456789")
+            .match_body(Matcher::Json(json!({
+                "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
+                "user_id": "usr_01EHZNVPK3SFK441A1RGBFSHRT",
+                "scopes": ["widgets:users-table:manage"]
+            })))
+            .with_status(201)
+            .with_body(
+                json!({
+                    "token": "token"
+                })
+                .to_string(),
+            )
+            .create_async()
+            .await;
+
+        let GenerateTokenResponse { token } = workos
+            .widgets()
+            .generate_token(&GenerateTokenParams {
+                organization_id: &OrganizationId::from("org_01EHZNVPK3SFK441A1RGBFSHRT"),
+                user_id: Some(&UserId::from("usr_01EHZNVPK3SFK441A1RGBFSHRT")),
+                scopes: Some(vec![WidgetTokenScope::ManageUsers]),
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(token, "token".to_string())
+    }
+}

src/workos.rs

@@ -10,6 +10,7 @@ use crate::portal::Portal;
 use crate::roles::Roles;
 use crate::sso::Sso;
 use crate::user_management::UserManagement;
+use crate::widgets::Widgets;
 
 /// The WorkOS client.
 #[derive(Clone)]
@@ -86,6 +87,11 @@ impl WorkOs {
     pub fn user_management(&self) -> UserManagement<'_> {
         UserManagement::new(self)
     }
+
+    /// Returns an [`Widgets`] instance.
+    pub fn widgets(&self) -> Widgets<'_> {
+        Widgets::new(self)
+    }
 }
 
 /// A builder for a WorkOS client.