document types

crates/api_clients/artcraft/artcraft_api_defs/src/moderation/mod.rs

@@ -1,5 +1,6 @@
 pub mod alerts;
 pub mod jobs;
 pub mod user;
+pub mod user_referrals;
 pub mod wallet_ledger_entries;
 pub mod wallets;

crates/api_clients/artcraft/artcraft_api_defs/src/moderation/user_referrals/list_global_user_referrals.rs

@@ -0,0 +1,47 @@
+use chrono::{DateTime, Utc};
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::user_referral_codes::UserReferralCodeToken;
+use tokens::tokens::users::UserToken;
+use utoipa::{IntoParams, ToSchema};
+
+// --- Request ---
+
+#[derive(Deserialize, ToSchema, IntoParams)]
+pub struct ListGlobalUserReferralsQueryParams {
+  pub cursor: Option<String>,
+  pub limit: Option<u32>,
+}
+
+// --- Response ---
+
+#[derive(Serialize, ToSchema)]
+pub struct ListGlobalUserReferralsSuccessResponse {
+  pub success: bool,
+  pub referrals: Vec<UserReferralResponse>,
+  pub maybe_cursor: Option<String>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct UserReferralResponse {
+  pub invited_user: InvitedUserDetails,
+  pub referrer_user: ReferrerUserDetails,
+  pub maybe_referral_code_token: Option<UserReferralCodeToken>,
+  pub maybe_referral_url: Option<String>,
+  pub maybe_landing_url: Option<String>,
+  pub created_at: DateTime<Utc>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct InvitedUserDetails {
+  pub token: UserToken,
+  pub username: String,
+  pub display_name: String,
+  pub email_address: String,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct ReferrerUserDetails {
+  pub token: UserToken,
+  pub username: String,
+  pub display_name: String,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/moderation/user_referrals/list_user_referrals_for_user.rs

@@ -0,0 +1,26 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
+
+use crate::moderation::user_referrals::list_global_user_referrals::UserReferralResponse;
+
+// --- Request ---
+
+#[derive(Deserialize, ToSchema, IntoParams)]
+pub struct ListUserReferralsForUserQueryParams {
+  pub cursor: Option<String>,
+  pub limit: Option<u32>,
+}
+
+#[derive(Deserialize, ToSchema)]
+pub struct ListUserReferralsForUserPathInfo {
+  pub username: String,
+}
+
+// --- Response ---
+
+#[derive(Serialize, ToSchema)]
+pub struct ListUserReferralsForUserSuccessResponse {
+  pub success: bool,
+  pub referrals: Vec<UserReferralResponse>,
+  pub maybe_cursor: Option<String>,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/moderation/user_referrals/mod.rs

@@ -0,0 +1,2 @@
+pub mod list_global_user_referrals;
+pub mod list_user_referrals_for_user;

crates/service/web/storyteller_web/src/docs/api_doc.rs

@@ -93,6 +93,8 @@ use crate::http_server::endpoints::moderation::user_feature_flags::moderator_lis
 use crate::http_server::endpoints::moderation::user_feature_flags::moderator_list_user_feature_flags_handler::*;
 use crate::http_server::endpoints::moderation::staff_audit_logs::moderator_list_staff_audit_logs_handler::*;
 use crate::http_server::endpoints::moderation::user_bans::moderation_ban_user_handler::*;
+use artcraft_api_defs::moderation::user_referrals::list_global_user_referrals::*;
+use artcraft_api_defs::moderation::user_referrals::list_user_referrals_for_user::*;
 use crate::http_server::endpoints::moderation::user_sessions::moderator_list_user_session_impersonation_requests_for_user_handler::*;
 use crate::http_server::endpoints::moderation::user_sessions::moderator_list_user_session_impersonation_requests_handler::*;
 use crate::http_server::endpoints::moderation::user_sessions::moderator_user_session_impersonation_request_handler::*;
@@ -529,6 +531,8 @@ use crate::http_server::endpoints::media_files::list::list_batch_generated_redux
     crate::http_server::endpoints::moderation::debug_logs::moderation_list_debug_logs_for_token_handler::moderation_list_debug_logs_for_token_handler,
     crate::http_server::endpoints::moderation::jobs::moderation_get_job_by_token_handler::moderation_get_job_by_token_handler,
     crate::http_server::endpoints::moderation::staff_audit_logs::moderator_list_staff_audit_logs_handler::moderator_list_staff_audit_logs_handler,
+    crate::http_server::endpoints::moderation::user_referrals::moderator_list_global_user_referrals_handler::moderator_list_global_user_referrals_handler,
+    crate::http_server::endpoints::moderation::user_referrals::moderator_list_user_referrals_for_user_handler::moderator_list_user_referrals_for_user_handler,
     crate::http_server::endpoints::moderation::user_bans::moderation_ban_user_handler::moderation_ban_user_handler,
     crate::http_server::endpoints::moderation::user_sessions::moderator_list_user_session_impersonation_requests_for_user_handler::moderator_list_user_session_impersonation_requests_for_user_handler,
     crate::http_server::endpoints::moderation::user_sessions::moderator_list_user_session_impersonation_requests_handler::moderator_list_user_session_impersonation_requests_handler,
@@ -1225,6 +1229,16 @@ use crate::http_server::endpoints::media_files::list::list_batch_generated_redux
     ReferralCodeEntry,
     DeleteReferralCodePathInfo,
     DeleteReferralCodeResponse,
+
+    // User Referrals (Moderation)
+    ListGlobalUserReferralsQueryParams,
+    ListGlobalUserReferralsSuccessResponse,
+    UserReferralResponse,
+    InvitedUserDetails,
+    ReferrerUserDetails,
+    ListUserReferralsForUserQueryParams,
+    ListUserReferralsForUserPathInfo,
+    ListUserReferralsForUserSuccessResponse,
   ))
 )]
 pub struct ApiDoc;

crates/service/web/storyteller_web/src/http_server/endpoints/moderation/user_referrals/moderator_list_global_user_referrals_handler.rs

@@ -2,15 +2,15 @@ use std::sync::Arc;
 
 use actix_web::web::{Json, Query};
 use actix_web::{web, HttpRequest};
-use chrono::{DateTime, Utc};
 use log::warn;
-use utoipa::{IntoParams, ToSchema};
 
+use artcraft_api_defs::moderation::user_referrals::list_global_user_referrals::{
+  InvitedUserDetails, ListGlobalUserReferralsQueryParams,
+  ListGlobalUserReferralsSuccessResponse, ReferrerUserDetails, UserReferralResponse,
+};
 use mysql_queries::queries::user_referrals::list_global_user_referrals::{
   list_global_user_referrals, ListGlobalUserReferralsArgs,
 };
-use tokens::tokens::user_referral_codes::UserReferralCodeToken;
-use tokens::tokens::users::UserToken;
 
 use crate::http_server::common_responses::advanced_common_web_error::AdvancedCommonWebError;
 use crate::http_server::web_utils::user_session::require_moderator::{
@@ -22,50 +22,6 @@ const CURSOR_NAME: &str = "modusrref";
 const DEFAULT_LIMIT: u32 = 100;
 const MAX_LIMIT: u32 = 1000;
 
-// --- Request ---
-
-#[derive(Deserialize, ToSchema, IntoParams)]
-pub struct ListGlobalUserReferralsQueryParams {
-  pub cursor: Option<String>,
-  pub limit: Option<u32>,
-}
-
-// --- Response ---
-
-#[derive(Serialize, ToSchema)]
-pub struct ListGlobalUserReferralsSuccessResponse {
-  pub success: bool,
-  pub referrals: Vec<UserReferralResponse>,
-  pub maybe_cursor: Option<String>,
-}
-
-#[derive(Serialize, ToSchema)]
-pub struct UserReferralResponse {
-  pub invited_user: InvitedUserDetails,
-  pub referrer_user: ReferrerUserDetails,
-  pub maybe_referral_code_token: Option<UserReferralCodeToken>,
-  pub maybe_referral_url: Option<String>,
-  pub maybe_landing_url: Option<String>,
-  pub created_at: DateTime<Utc>,
-}
-
-#[derive(Serialize, ToSchema)]
-pub struct InvitedUserDetails {
-  pub token: UserToken,
-  pub username: String,
-  pub display_name: String,
-  pub email_address: String,
-}
-
-#[derive(Serialize, ToSchema)]
-pub struct ReferrerUserDetails {
-  pub token: UserToken,
-  pub username: String,
-  pub display_name: String,
-}
-
-// --- Handler ---
-
 /// List all user referrals globally. Moderators only.
 #[utoipa::path(
   get,

crates/service/web/storyteller_web/src/http_server/endpoints/moderation/user_referrals/moderator_list_user_referrals_for_user_handler.rs

@@ -3,16 +3,19 @@ use std::sync::Arc;
 use actix_web::web::{Json, Path, Query};
 use actix_web::{web, HttpRequest};
 use log::warn;
-use utoipa::{IntoParams, ToSchema};
 
+use artcraft_api_defs::moderation::user_referrals::list_global_user_referrals::{
+  InvitedUserDetails, ReferrerUserDetails, UserReferralResponse,
+};
+use artcraft_api_defs::moderation::user_referrals::list_user_referrals_for_user::{
+  ListUserReferralsForUserPathInfo, ListUserReferralsForUserQueryParams,
+  ListUserReferralsForUserSuccessResponse,
+};
 use mysql_queries::queries::user_referrals::list_user_referrals_for_user::{
   list_user_referrals_for_user, ListUserReferralsForUserArgs,
 };
 
 use crate::http_server::common_responses::advanced_common_web_error::AdvancedCommonWebError;
-use crate::http_server::endpoints::moderation::user_referrals::moderator_list_global_user_referrals_handler::{
-  InvitedUserDetails, ReferrerUserDetails, UserReferralResponse,
-};
 use crate::http_server::web_utils::user_session::require_moderator::{
   require_moderator, UseDatabase,
 };
@@ -22,30 +25,6 @@ const CURSOR_NAME: &str = "modusrrefu";
 const DEFAULT_LIMIT: u32 = 100;
 const MAX_LIMIT: u32 = 1000;
 
-// --- Request ---
-
-#[derive(Deserialize, ToSchema, IntoParams)]
-pub struct ListUserReferralsForUserQueryParams {
-  pub cursor: Option<String>,
-  pub limit: Option<u32>,
-}
-
-#[derive(Deserialize, ToSchema)]
-pub struct ListUserReferralsForUserPathInfo {
-  pub username: String,
-}
-
-// --- Response ---
-
-#[derive(Serialize, ToSchema)]
-pub struct ListUserReferralsForUserSuccessResponse {
-  pub success: bool,
-  pub referrals: Vec<UserReferralResponse>,
-  pub maybe_cursor: Option<String>,
-}
-
-// --- Handler ---
-
 /// List user referrals for a specific referrer user. Moderators only.
 #[utoipa::path(
   get,