fixes to new endpoint

more performant list user files endpoint

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/legacy_media_file_cover_image_details.rs

@@ -0,0 +1,30 @@
+use serde_derive::{Deserialize, Serialize};
+use url::Url;
+use utoipa::ToSchema;
+
+use crate::common::responses::cover_image_links::CoverImageLinks;
+use crate::common::responses::media_file_cover_image_details::MediaFileDefaultCover;
+
+// User-media list endpoints retain the deprecated bucket fields for compatibility.
+/// Everything we need to create a cover image.
+/// Cover images are small descriptive images that can be set for any media file.
+/// If a cover image is set, this is the path to the asset.
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct LegacyMediaFileCoverImageDetails {
+  /// (DEPRECATED) URL path to the media file
+  #[deprecated(note="This field doesn't point to the full URL. Use media_links instead to leverage the CDN.")]
+  pub maybe_cover_image_public_bucket_path: Option<String>,
+
+  /// (DEPRECATED) Full URL to the media file
+  #[deprecated(note="This points to the bucket. Use media_links instead to leverage the CDN.")]
+  pub maybe_cover_image_public_bucket_url: Option<Url>,
+
+  /// Links to the cover image (CDN direct link, thumbnail template)
+  /// If a cover image is set, this is the path to the asset.
+  /// If a cover image is not set, use the information in `default_cover` instead.
+  /// Rich CDN links to the media, including thumbnails, previews, and more.
+  pub maybe_links: Option<CoverImageLinks>,
+
+  /// For items without a cover image, we can use one of our own.
+  pub default_cover: MediaFileDefaultCover,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/media_file_origin_details.rs

@@ -0,0 +1,44 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use enums::by_table::media_files::media_file_origin_category::MediaFileOriginCategory;
+use enums::by_table::media_files::media_file_origin_model_type::MediaFileOriginModelType;
+use enums::by_table::media_files::media_file_origin_product_category::MediaFileOriginProductCategory;
+use tokens::tokens::model_weights::ModelWeightToken;
+
+/// Fields useful for enriching media file listings
+#[derive(Clone, Serialize, Deserialize, ToSchema)]
+pub struct MediaFileOriginDetails {
+  /// Where the file came from (broadly)
+  pub origin_category: MediaFileOriginCategory,
+
+  /// Where the file came from (specifically, a product area, eg. "face_animator")
+  pub product_category: MediaFileOriginProductCategory,
+
+  /// If the file was produced by a model, the details.
+  pub maybe_model: Option<MediaFileModelDetails>,
+}
+
+/// Information about the model weights
+/// https://serde.rs/enum-representations.html#untagged
+#[derive(Clone, Serialize, Deserialize, ToSchema)]
+#[serde(untagged)]
+pub enum MediaFileModelDetails {
+  // Try the specific shape first so deserialization retains token and title.
+  /// A model weight is typically a user-submitted model.
+  /// We store lots of these.
+  ModelWeight {
+    /// The type of model weight
+    model_type: MediaFileOriginModelType,
+    /// The model token
+    token: ModelWeightToken,
+    /// The model title (typically only populated for `model_weights` models, not legacy tables such as `tts_models`.)
+    title: String,
+  },
+  /// A system model is one that we maintain and update,
+  /// eg. SadTalker, Wav2Lip, MocapNet, etc.
+  SystemModel {
+    /// The type of model weight
+    model_type: MediaFileOriginModelType,
+  },
+}

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/mod.rs

@@ -1,8 +1,10 @@
 pub mod cover_image_links;
 pub mod job_details;
+pub mod legacy_media_file_cover_image_details;
 pub mod media_file_cover_image_details;
+pub mod media_file_origin_details;
 pub mod media_links;
 pub mod pagination_cursors;
 pub mod simple_entity_stats;
 pub mod simple_generic_json_success;
-pub mod user_details_light;
+pub mod user_details_light;

crates/api_clients/artcraft/artcraft_api_defs/src/common/responses/simple_entity_stats.rs

@@ -1,9 +1,10 @@
 use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
 // TODO(bt,2025-08-20): Replace the storyteller-web version of this.
 
 /// Simple stats that can be attached to any entity
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, ToSchema, Debug)]
 pub struct SimpleEntityStats {
   /// Number of positive ratings (or "likes") for this item
   pub positive_rating_count: u32,

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/list/list_media_files_for_user_v2.rs

@@ -0,0 +1,67 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
+
+use crate::media_file::list::user_media_file_list_item::MediaFileForUserListItem;
+
+pub const LIST_MEDIA_FILES_FOR_USER_V2_URL_PATH: &str = "/v1/media_files/list_v2/user/{username}";
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct ListMediaFilesForUserV2PathInfo {
+  pub username: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema, IntoParams)]
+pub struct ListMediaFilesForUserV2QueryParams {
+  pub sort_ascending: Option<bool>,
+  pub page_size: Option<usize>,
+  pub page_index: Option<usize>,
+
+  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`,
+  /// which are the broad category of media files: image, video, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_classes=audio`
+  ///   - `?filter_media_classes=image,video`
+  ///   - `?filter_media_classes=dimensional`
+  ///   - etc.
+  pub filter_media_classes: Option<String>,
+
+  /// NB: This can be one (or more comma-separated values) from `MediaFileType`,
+  /// which are mimetype-like / format-like categories of media files: glb, gltf,
+  /// scene_json, jpg, png, mp4, wav, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_type=scene_json`
+  ///   - `?filter_media_type=glb,gltf,fbx`
+  ///   - `?filter_media_type=pmd,vmd,pmx`
+  ///   - `?filter_media_type=jpg,png,gif`
+  ///   - `?filter_media_type=wav,mp3`
+  ///   - `?filter_media_type=mp4`
+  ///   - etc.
+  pub filter_media_type: Option<String>,
+
+  /// NB: This can be one (or more comma-separated values) from `MediaFileEngineCategory`.
+  ///
+  /// Usage:
+  ///   - `?filter_engine_categories=scene`
+  ///   - `?filter_engine_categories=animation,character,object`
+  ///   - etc.
+  pub filter_engine_categories: Option<String>,
+
+  /// Include user uploaded files in the results.
+  /// By default, we do not return them unless this flag is set to true.
+  pub include_user_uploads: Option<bool>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct ListMediaFilesForUserV2SuccessResponse {
+  pub success: bool,
+  pub results: Vec<MediaFileForUserListItem>,
+  pub pagination: UserMediaFileV2Pagination,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct UserMediaFileV2Pagination {
+  pub current: usize,
+  pub has_more: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/list/mod.rs

@@ -1 +1,3 @@
 pub mod by_type;
+pub mod list_media_files_for_user_v2;
+pub mod user_media_file_list_item;

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/list/user_media_file_list_item.rs

@@ -0,0 +1,106 @@
+use chrono::{DateTime, Utc};
+use enums::by_table::media_files::media_file_animation_type::MediaFileAnimationType;
+use enums::by_table::media_files::media_file_class::MediaFileClass;
+use enums::by_table::media_files::media_file_engine_category::MediaFileEngineCategory;
+use enums::by_table::media_files::media_file_origin_category::MediaFileOriginCategory;
+use enums::by_table::media_files::media_file_origin_model_type::MediaFileOriginModelType;
+use enums::by_table::media_files::media_file_origin_product_category::MediaFileOriginProductCategory;
+use enums::by_table::media_files::media_file_type::MediaFileType;
+use enums::common::visibility::Visibility;
+use enums::no_table::style_transfer::style_transfer_name::StyleTransferName;
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::media_files::MediaFileToken;
+use tokens::tokens::prompts::PromptToken;
+use utoipa::ToSchema;
+
+use crate::common::responses::legacy_media_file_cover_image_details::LegacyMediaFileCoverImageDetails;
+use crate::common::responses::media_file_origin_details::MediaFileOriginDetails;
+use crate::common::responses::media_links::MediaLinks;
+use crate::common::responses::simple_entity_stats::SimpleEntityStats;
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct MediaFileForUserListItem {
+  pub token: MediaFileToken,
+
+  /// The coarse-grained class of media file: image, video, etc.
+  pub media_class: MediaFileClass,
+
+  /// Type of media will dictate which fields are populated and what
+  /// the frontend should display (eg. video player vs audio player).
+  /// This is closer in meaning to a "mime type".
+  pub media_type: MediaFileType,
+
+  /// If this is an engine/3D asset, this is the broad category (scene,
+  /// animation, etc.) of that object.
+  /// This can also be used for filtering in list/batch endpoints.
+  pub maybe_engine_category: Option<MediaFileEngineCategory>,
+
+  /// If this is an engine/3D asset for an animation or a rig that can
+  /// be animated with either (or both) skeletal or blend shape animations,
+  /// this describes the animation regime used or supported.
+  pub maybe_animation_type: Option<MediaFileAnimationType>,
+
+  /// Details where the media file came from.
+  pub origin: MediaFileOriginDetails,
+
+  #[deprecated(note="Use MediaFileOriginDetails instead")]
+  pub origin_category: MediaFileOriginCategory,
+
+  #[deprecated(note="Use MediaFileOriginDetails instead")]
+  pub origin_product_category: MediaFileOriginProductCategory,
+
+  #[deprecated(note="Use MediaFileOriginDetails instead")]
+  pub maybe_origin_model_type: Option<MediaFileOriginModelType>,
+
+  #[deprecated(note="Use MediaFileOriginDetails instead")]
+  pub maybe_origin_model_token: Option<String>,
+
+  /// (DEPRECATED) URL path to the media file
+  #[deprecated(note="This field doesn't point to the full URL. Use media_links instead to leverage the CDN.")]
+  pub public_bucket_path: String,
+
+  /// (DEPRECATED) Full URL to the media file
+  #[deprecated(note="This points to the bucket. Use media_links instead to leverage the CDN.")]
+  pub public_bucket_url: String,
+
+  /// Rich CDN links to the media, including thumbnails, previews, and more.
+  pub media_links: MediaLinks,
+
+  /// The foreign key to the prompt used to generate the media, if applicable.
+  pub maybe_prompt_token: Option<PromptToken>,
+
+  /// Information about the cover image. Many media files do not require a cover image,
+  /// e.g. image files, video files with thumbnails, audio files, etc.
+  /// 3D files require them.
+  pub cover_image: LegacyMediaFileCoverImageDetails,
+
+  pub creator_set_visibility: Visibility,
+
+  /// The file was uploaded by the user.
+  /// This does not include files generated on the client side, like studio renders.
+  pub is_user_upload: bool,
+
+  /// The file was created by the system.
+  /// This includes files generated on the client side, like studio renders.
+  pub is_intermediate_system_file: bool,
+
+  /// The name or title of the media file (optional)
+  pub maybe_title: Option<String>,
+
+  /// Text transcripts for TTS, etc.
+  pub maybe_text_transcript: Option<String>,
+
+  /// For Comfy / Video Style Transfer jobs, this might include
+  /// the name of the selected style.
+  pub maybe_style_name: Option<StyleTransferName>,
+
+  /// Duration for audio and video files, if available.
+  /// Measured in milliseconds.
+  pub maybe_duration_millis: Option<u64>,
+
+  /// Statistics about the media file
+  pub stats: SimpleEntityStats,
+
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+}

crates/lib/actix_cors_configs/src/configs/artcraft_desktop.rs

@@ -0,0 +1,66 @@
+use actix_cors::Cors;
+
+pub fn add_artcraft_desktop(cors: Cors, _is_production: bool) -> Cors {
+  cors
+      // Stable identity sent by the Artcraft native HTTP bridge (dev and packaged apps).
+      .allowed_origin("https://desktop.getartcraft.com")
+}
+
+#[cfg(test)]
+mod tests {
+  use actix_web::dev::Transform;
+  use actix_web::http::{header, Method, StatusCode};
+  use actix_web::test::{self, TestRequest};
+  use server_environment::ServerEnvironment;
+
+  use crate::cors::build_cors_config;
+  use crate::testing::{assert_origin_invalid, assert_origin_ok};
+
+  const DESKTOP_ORIGIN: &str = "https://desktop.getartcraft.com";
+
+  #[actix_rt::test]
+  async fn desktop_requests_and_preflights_allow_credentials() {
+    for environment in [ServerEnvironment::Production, ServerEnvironment::Development] {
+      let service = build_cors_config(environment)
+          .new_transform(test::ok_service())
+          .await
+          .unwrap();
+
+      for method in [Method::GET, Method::POST, Method::OPTIONS] {
+        let mut request = TestRequest::default()
+            .uri("/v1/session")
+            .insert_header((header::ORIGIN, DESKTOP_ORIGIN));
+        if method == Method::OPTIONS {
+          request = request
+              .insert_header((header::ACCESS_CONTROL_REQUEST_METHOD, "POST"))
+              .insert_header((header::ACCESS_CONTROL_REQUEST_HEADERS, "content-type,session,x-artcraft-version"));
+        }
+        let response = test::call_service(&service, request.method(method).to_srv_request()).await;
+        assert_eq!(response.status(), StatusCode::OK);
+        assert_eq!(response.headers().get(header::ACCESS_CONTROL_ALLOW_ORIGIN).unwrap(), DESKTOP_ORIGIN);
+        assert_eq!(response.headers().get(header::ACCESS_CONTROL_ALLOW_CREDENTIALS).unwrap(), "true");
+      }
+    }
+  }
+
+  #[actix_rt::test]
+  async fn desktop_origin_is_an_exact_https_allowlist_entry() {
+    let cors = build_cors_config(ServerEnvironment::Production);
+    for origin in [
+      "http://desktop.getartcraft.com",
+      "https://desktop.getartcraft.com:8443",
+      "https://desktop.getartcraft.com.example.com",
+      "https://sub.desktop.getartcraft.com",
+    ] {
+      assert_origin_invalid(&cors, origin).await;
+    }
+  }
+
+  #[actix_rt::test]
+  async fn existing_desktop_clients_remain_allowed() {
+    let cors = build_cors_config(ServerEnvironment::Production);
+    for origin in ["https://studio.storyteller.ai", "http://tauri.localhost", "tauri://localhost"] {
+      assert_origin_ok(&cors, origin).await;
+    }
+  }
+}

crates/lib/actix_cors_configs/src/configs/mod.rs

@@ -1,6 +1,7 @@
 pub (crate) mod artcraft_admin_dashboard;
 pub (crate) mod artcraft_2d;
 pub (crate) mod artcraft_3d;
+pub (crate) mod artcraft_desktop;
 pub (crate) mod artcraft_webapp;
 pub (crate) mod artcraft_website;
 pub (crate) mod development_only;
@@ -11,4 +12,4 @@ pub (crate) mod storyteller;
 pub (crate) mod storyteller_board;
 pub (crate) mod storyteller_render;
 pub (crate) mod storyteller_studio;
-pub (crate) mod tauri;
+pub (crate) mod tauri;

crates/lib/actix_cors_configs/src/configs/tauri.rs

@@ -7,3 +7,86 @@ pub fn add_tauri(cors: Cors, _is_production: bool) -> Cors {
       // Tauri Mac
       .allowed_origin("tauri://localhost")
 }
+
+#[cfg(test)]
+mod tests {
+  use actix_web::dev::Transform;
+  use actix_web::http::{header, Method, StatusCode};
+  use actix_web::test::{self, TestRequest};
+  use server_environment::ServerEnvironment;
+
+  use crate::cors::build_cors_config;
+  use crate::testing::assert_origin_invalid;
+
+  const WINDOWS_ORIGIN: &str = "http://tauri.localhost";
+  const MAC_ORIGIN: &str = "tauri://localhost";
+
+  mod windows {
+    use super::*;
+
+    #[actix_rt::test]
+    async fn requests_and_preflights_allow_credentials() {
+      assert_requests_and_preflights_allow_credentials(WINDOWS_ORIGIN).await;
+    }
+
+    #[actix_rt::test]
+    async fn production_rejects_origin_variants() {
+      let cors = build_cors_config(ServerEnvironment::Production);
+      for origin in [
+        "https://tauri.localhost",
+        "http://tauri.localhost:8080",
+        "http://tauri.localhost.example.com",
+        "http://sub.tauri.localhost",
+      ] {
+        assert_origin_invalid(&cors, origin).await;
+      }
+    }
+  }
+
+  mod mac {
+    use super::*;
+
+    #[actix_rt::test]
+    async fn requests_and_preflights_allow_credentials() {
+      assert_requests_and_preflights_allow_credentials(MAC_ORIGIN).await;
+    }
+
+    #[actix_rt::test]
+    async fn production_rejects_origin_variants() {
+      let cors = build_cors_config(ServerEnvironment::Production);
+      for origin in [
+        "http://localhost",
+        "https://localhost",
+        "tauri://localhost:8080",
+        "tauri://localhost.example.com",
+        "tauri://sub.localhost",
+      ] {
+        assert_origin_invalid(&cors, origin).await;
+      }
+    }
+  }
+
+  async fn assert_requests_and_preflights_allow_credentials(origin: &str) {
+    for environment in [ServerEnvironment::Production, ServerEnvironment::Development] {
+      let service = build_cors_config(environment)
+          .new_transform(test::ok_service())
+          .await
+          .unwrap();
+
+      for method in [Method::GET, Method::POST, Method::OPTIONS] {
+        let mut request = TestRequest::default()
+            .uri("/v1/session")
+            .insert_header((header::ORIGIN, origin));
+        if method == Method::OPTIONS {
+          request = request
+              .insert_header((header::ACCESS_CONTROL_REQUEST_METHOD, "POST"))
+              .insert_header((header::ACCESS_CONTROL_REQUEST_HEADERS, "content-type,session,x-artcraft-version"));
+        }
+        let response = test::call_service(&service, request.method(method).to_srv_request()).await;
+        assert_eq!(response.status(), StatusCode::OK, "Origin: {}", origin);
+        assert_eq!(response.headers().get(header::ACCESS_CONTROL_ALLOW_ORIGIN).unwrap(), origin);
+        assert_eq!(response.headers().get(header::ACCESS_CONTROL_ALLOW_CREDENTIALS).unwrap(), "true");
+      }
+    }
+  }
+}

crates/lib/actix_cors_configs/src/cors.rs

@@ -4,6 +4,7 @@ use log::info;
 use crate::configs::artcraft_2d::add_artcraft_2d;
 use crate::configs::artcraft_3d::add_artcraft_3d;
 use crate::configs::artcraft_admin_dashboard::add_artcraft_admin_dashboard;
+use crate::configs::artcraft_desktop::add_artcraft_desktop;
 use crate::configs::artcraft_webapp::add_artcraft_webapp;
 use crate::configs::artcraft_website::add_artcraft_website;
 use crate::configs::development_only::add_development_only;
@@ -48,6 +49,7 @@ fn do_build_cors_config(is_production: bool) -> Cors {
 
   // Artcraft
   cors = add_tauri(cors, is_production);
+  cors = add_artcraft_desktop(cors, is_production);
   cors = add_artcraft_2d(cors, is_production);
   cors = add_artcraft_3d(cors, is_production);
   cors = add_artcraft_webapp(cors, is_production);

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

@@ -59,7 +59,6 @@ use crate::http_server::endpoints::media_files::get::get_media_file_handler::*;
 use crate::http_server::endpoints::media_files::list::list_featured_media_files_handler::*;
 use crate::http_server::endpoints::media_files::list::list_media_files_by_batch_token_handler::*;
 use crate::http_server::endpoints::media_files::list::list_media_files_for_user_handler::*;
-use crate::http_server::endpoints::media_files::list::list_media_files_for_user_v2_handler::*;
 use crate::http_server::endpoints::media_files::list::list_media_files_handler::*;
 use crate::http_server::endpoints::media_files::list::list_pinned_media_files_handler::*;
 use crate::http_server::endpoints::media_files::search::search_featured_media_files_handler::*;
@@ -379,6 +378,12 @@ use artcraft_api_defs::media_file::list::by_type::list_session_common::*;
 use artcraft_api_defs::media_file::job::list_media_files_by_job::*;
 use artcraft_api_defs::media_file::list::by_type::list_session_mesh_media_files::*;
 use artcraft_api_defs::media_file::list::by_type::list_session_splat_media_files::*;
+use artcraft_api_defs::media_file::list::list_media_files_for_user_v2::{
+  ListMediaFilesForUserV2PathInfo, ListMediaFilesForUserV2QueryParams,
+  ListMediaFilesForUserV2SuccessResponse, UserMediaFileV2Pagination,
+};
+use artcraft_api_defs::media_file::list::user_media_file_list_item::MediaFileForUserListItem;
+use artcraft_api_defs::common::responses::legacy_media_file_cover_image_details::LegacyMediaFileCoverImageDetails;
 use artcraft_api_defs::media_file::list_session_project_media_files::*;
 use artcraft_api_defs::media_file::project::upload_updated_mood_board_project::*;
 use artcraft_api_defs::media_file::project::upload_new_mood_board_project::*;
@@ -1142,6 +1147,7 @@ use crate::http_server::endpoints::media_files::list::list_batch_generated_redux
     InferTtsSuccessResponse,
     InferenceJobStatusResponsePayload,
     InferenceJobTokenType,
+    LegacyMediaFileCoverImageDetails,
     LegacyQueueDetails,
     ListActiveUserSubscriptionsResponse,
     ListAvailableWeightsQuery,

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs

@@ -1,33 +1,18 @@
 use std::sync::Arc;
 
 use actix_web::web::{Json, Path, Query};
-use actix_web::{web, HttpMessage, HttpRequest, HttpResponse};
-use artcraft_api_defs::common::responses::media_links::MediaLinks;
-use chrono::{DateTime, Utc};
-use enums::by_table::media_files::media_file_animation_type::MediaFileAnimationType;
-use enums::by_table::media_files::media_file_class::MediaFileClass;
-use enums::by_table::media_files::media_file_engine_category::MediaFileEngineCategory;
-use enums::by_table::media_files::media_file_origin_category::MediaFileOriginCategory;
-use enums::by_table::media_files::media_file_origin_product_category::MediaFileOriginProductCategory;
-use enums::by_table::media_files::media_file_type::MediaFileType;
+use actix_web::{web, HttpRequest};
+use artcraft_api_defs::media_file::list::user_media_file_list_item::MediaFileForUserListItem;
 use enums::common::view_as::ViewAs;
-use enums::common::visibility::Visibility;
-use enums::no_table::style_transfer::style_transfer_name::StyleTransferName;
-use enums::by_table::media_files::media_file_origin_model_type::MediaFileOriginModelType;
 use log::info;
 use std::time::Instant;
 use mysql_queries::queries::media_files::list::list_media_files_for_user::{list_media_files_for_user, ListMediaFileForUserArgs};
 use mysql_queries::queries::media_files::list::count_media_files_for_user::{count_media_files_for_user, CountMediaFilesForUserArgs};
 use mysql_queries::queries::media_files::list::user_media_file_filters::UserMediaFileFilters;
 use super::user_media_file_response::{build_user_media_file_response, UserMediaFileResponseArgs};
-use tokens::tokens::media_files::MediaFileToken;
 use utoipa::{IntoParams, ToSchema};
-use tokens::tokens::prompts::PromptToken;
 use crate::http_server::common_responses::common_web_error::CommonWebError;
-use crate::http_server::common_responses::media::media_file_cover_image_details::MediaFileCoverImageDetails;
-use crate::http_server::common_responses::media_file_origin_details::MediaFileOriginDetails;
 use crate::http_server::common_responses::pagination_page::PaginationPage;
-use crate::http_server::common_responses::simple_entity_stats::SimpleEntityStats;
 use crate::http_server::endpoints::media_files::helpers::get_media_domain::get_media_domain;
 use crate::http_server::endpoints::media_files::helpers::get_scoped_engine_categories::get_scoped_engine_categories;
 use crate::http_server::endpoints::media_files::helpers::get_scoped_media_classes::get_scoped_media_classes;
@@ -90,93 +75,6 @@ pub struct ListMediaFilesForUserSuccessResponse {
   pub pagination: PaginationPage,
 }
 
-#[derive(Serialize, ToSchema)]
-pub struct MediaFileForUserListItem {
-  pub token: MediaFileToken,
-
-  /// The coarse-grained class of media file: image, video, etc.
-  pub media_class: MediaFileClass,
-
-  /// Type of media will dictate which fields are populated and what
-  /// the frontend should display (eg. video player vs audio player).
-  /// This is closer in meaning to a "mime type".
-  pub media_type: MediaFileType,
-
-  /// If this is an engine/3D asset, this is the broad category (scene,
-  /// animation, etc.) of that object.
-  /// This can also be used for filtering in list/batch endpoints.
-  pub maybe_engine_category: Option<MediaFileEngineCategory>,
-
-  /// If this is an engine/3D asset for an animation or a rig that can
-  /// be animated with either (or both) skeletal or blend shape animations,
-  /// this describes the animation regime used or supported.
-  pub maybe_animation_type: Option<MediaFileAnimationType>,
-
-  /// Details where the media file came from.
-  pub origin: MediaFileOriginDetails,
-
-  #[deprecated(note="Use MediaFileOriginDetails instead")]
-  pub origin_category: MediaFileOriginCategory,
-
-  #[deprecated(note="Use MediaFileOriginDetails instead")]
-  pub origin_product_category: MediaFileOriginProductCategory,
-
-  #[deprecated(note="Use MediaFileOriginDetails instead")]
-  pub maybe_origin_model_type: Option<MediaFileOriginModelType>,
-
-  #[deprecated(note="Use MediaFileOriginDetails instead")]
-  pub maybe_origin_model_token: Option<String>,
-
-  /// (DEPRECATED) URL path to the media file
-  #[deprecated(note="This field doesn't point to the full URL. Use media_links instead to leverage the CDN.")]
-  pub public_bucket_path: String,
-
-  /// (DEPRECATED) Full URL to the media file
-  #[deprecated(note="This points to the bucket. Use media_links instead to leverage the CDN.")]
-  pub public_bucket_url: String,
-
-  /// Rich CDN links to the media, including thumbnails, previews, and more.
-  pub media_links: MediaLinks,
-
-  /// The foreign key to the prompt used to generate the media, if applicable.
-  pub maybe_prompt_token: Option<PromptToken>,
-
-  /// Information about the cover image. Many media files do not require a cover image,
-  /// e.g. image files, video files with thumbnails, audio files, etc.
-  /// 3D files require them.
-  pub cover_image: MediaFileCoverImageDetails,
-
-  pub creator_set_visibility: Visibility,
-
-  /// The file was uploaded by the user.
-  /// This does not include files generated on the client side, like studio renders.
-  pub is_user_upload: bool,
-
-  /// The file was created by the system.
-  /// This includes files generated on the client side, like studio renders.
-  pub is_intermediate_system_file: bool,
-
-  /// The name or title of the media file (optional)
-  pub maybe_title: Option<String>,
-
-  /// Text transcripts for TTS, etc.
-  pub maybe_text_transcript: Option<String>,
-
-  /// For Comfy / Video Style Transfer jobs, this might include
-  /// the name of the selected style.
-  pub maybe_style_name: Option<StyleTransferName>,
-
-  /// Duration for audio and video files, if available.
-  /// Measured in milliseconds.
-  pub maybe_duration_millis: Option<u64>,
-
-  /// Statistics about the media file
-  pub stats: SimpleEntityStats,
-
-  pub created_at: DateTime<Utc>,
-  pub updated_at: DateTime<Utc>,
-}
-
 /// List all of a user's media files (paginated).
 ///
 /// This endpoint uses the session to automatically show all files for the given user, but only

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_v2_handler.rs

@@ -3,15 +3,17 @@ use std::time::Instant;
 
 use actix_web::web::{Json, Path, Query};
 use actix_web::{web, HttpRequest};
+use artcraft_api_defs::media_file::list::list_media_files_for_user_v2::{
+  ListMediaFilesForUserV2PathInfo, ListMediaFilesForUserV2QueryParams,
+  ListMediaFilesForUserV2SuccessResponse, UserMediaFileV2Pagination,
+};
 use enums::common::view_as::ViewAs;
 use log::info;
 use mysql_queries::queries::media_files::list::list_media_files_for_user::{
   list_media_files_for_user, ListMediaFileForUserArgs,
 };
 use mysql_queries::queries::media_files::list::user_media_file_filters::UserMediaFileFilters;
-use utoipa::{IntoParams, ToSchema};
 
-use super::list_media_files_for_user_handler::MediaFileForUserListItem;
 use super::user_media_file_response::{build_user_media_file_response, UserMediaFileResponseArgs};
 use crate::http_server::common_responses::common_web_error::CommonWebError;
 use crate::http_server::endpoints::media_files::helpers::get_media_domain::get_media_domain;
@@ -21,67 +23,6 @@ use crate::http_server::endpoints::media_files::helpers::get_scoped_media_types:
 use crate::state::server_state::ServerState;
 use crate::util::allowed_studio_access::allowed_studio_access;
 
-#[derive(Deserialize, ToSchema)]
-pub struct ListMediaFilesForUserV2PathInfo {
-  username: String,
-}
-
-#[derive(Deserialize, ToSchema, IntoParams)]
-pub struct ListMediaFilesForUserV2QueryParams {
-  pub sort_ascending: Option<bool>,
-  pub page_size: Option<usize>,
-  pub page_index: Option<usize>,
-
-  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`,
-  /// which are the broad category of media files: image, video, etc.
-  ///
-  /// Usage:
-  ///   - `?filter_media_classes=audio`
-  ///   - `?filter_media_classes=image,video`
-  ///   - `?filter_media_classes=dimensional`
-  ///   - etc.
-  pub filter_media_classes: Option<String>,
-
-  /// NB: This can be one (or more comma-separated values) from `MediaFileType`,
-  /// which are mimetype-like / format-like categories of media files: glb, gltf,
-  /// scene_json, jpg, png, mp4, wav, etc.
-  ///
-  /// Usage:
-  ///   - `?filter_media_type=scene_json`
-  ///   - `?filter_media_type=glb,gltf,fbx`
-  ///   - `?filter_media_type=pmd,vmd,pmx`
-  ///   - `?filter_media_type=jpg,png,gif`
-  ///   - `?filter_media_type=wav,mp3`
-  ///   - `?filter_media_type=mp4`
-  ///   - etc.
-  pub filter_media_type: Option<String>,
-
-  /// NB: This can be one (or more comma-separated values) from `MediaFileEngineCategory`.
-  ///
-  /// Usage:
-  ///   - `?filter_engine_categories=scene`
-  ///   - `?filter_engine_categories=animation,character,object`
-  ///   - etc.
-  pub filter_engine_categories: Option<String>,
-
-  /// Include user uploaded files in the results.
-  /// By default, we do not return them unless this flag is set to true.
-  pub include_user_uploads: Option<bool>,
-}
-
-#[derive(Serialize, ToSchema)]
-pub struct ListMediaFilesForUserV2SuccessResponse {
-  pub success: bool,
-  pub results: Vec<MediaFileForUserListItem>,
-  pub pagination: UserMediaFileV2Pagination,
-}
-
-#[derive(Serialize, ToSchema)]
-pub struct UserMediaFileV2Pagination {
-  pub current: usize,
-  pub has_more: bool,
-}
-
 /// Faster user-media listing for infinite scroll.
 ///
 /// Unlike `/v1/media_files/list/user/{username}`, this endpoint skips the exact

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/user_media_file_response.rs

@@ -1,14 +1,20 @@
+use artcraft_api_defs::common::responses::cover_image_links::CoverImageLinks;
+use artcraft_api_defs::common::responses::legacy_media_file_cover_image_details::LegacyMediaFileCoverImageDetails;
+use artcraft_api_defs::common::responses::media_file_cover_image_details::MediaFileDefaultCover;
+use artcraft_api_defs::common::responses::media_file_origin_details::{
+  MediaFileModelDetails as MediaFileModelDetailsApi, MediaFileOriginDetails as MediaFileOriginDetailsApi,
+};
+use artcraft_api_defs::common::responses::simple_entity_stats::SimpleEntityStats;
+use artcraft_api_defs::media_file::list::user_media_file_list_item::MediaFileForUserListItem;
 use bucket_paths::legacy::typified_paths::public::media_files::bucket_file_path::MediaFileBucketPath;
 use enums::by_table::media_files::media_file_type::MediaFileType;
 use mysql_queries::queries::media_files::list::user_media_file_list_item::MediaFileListItem;
 use server_environment::ServerEnvironment;
 
-use super::list_media_files_for_user_handler::MediaFileForUserListItem;
 use crate::http_server::common_responses::media::media_domain::MediaDomain;
 use crate::http_server::common_responses::media::media_file_cover_image_details::MediaFileCoverImageDetails;
 use crate::http_server::common_responses::media::media_links_builder::MediaLinksBuilder;
-use crate::http_server::common_responses::media_file_origin_details::MediaFileOriginDetails;
-use crate::http_server::common_responses::simple_entity_stats::SimpleEntityStats;
+use crate::http_server::common_responses::media_file_origin_details::{MediaFileModelDetails, MediaFileOriginDetails};
 use crate::http_server::web_utils::bucket_urls::bucket_url_string_from_media_path::bucket_url_string_from_media_path;
 
 pub(super) struct UserMediaFileResponseArgs {
@@ -62,13 +68,13 @@ pub(super) fn build_user_media_file_response(args: UserMediaFileResponseArgs) ->
         media_type: record.media_type,
         maybe_engine_category: record.maybe_engine_category,
         maybe_animation_type: record.maybe_animation_type,
-        origin: MediaFileOriginDetails::from_db_fields_str(
+        origin: into_api_origin(MediaFileOriginDetails::from_db_fields_str(
           record.origin_category,
           record.origin_product_category,
           record.maybe_origin_model_type,
           record.maybe_origin_model_token.as_deref(),
           record.maybe_origin_model_title.as_deref(),
-        ),
+        )),
         origin_category: record.origin_category,
         origin_product_category: record.origin_product_category,
         maybe_origin_model_type: record.maybe_origin_model_type,
@@ -77,14 +83,14 @@ pub(super) fn build_user_media_file_response(args: UserMediaFileResponseArgs) ->
         maybe_prompt_token: record.maybe_prompt_token,
         public_bucket_path: public_bucket_path.get_full_object_path_str().to_string(),
         public_bucket_url: bucket_url_string_from_media_path(&public_bucket_path, media_domain, server_environment),
-        cover_image: MediaFileCoverImageDetails::from_optional_db_fields(
+        cover_image: into_api_cover_image(MediaFileCoverImageDetails::from_optional_db_fields(
           &record.token,
           media_domain,
           server_environment,
           record.maybe_file_cover_image_public_bucket_hash.as_deref(),
           record.maybe_file_cover_image_public_bucket_prefix.as_deref(),
           record.maybe_file_cover_image_public_bucket_extension.as_deref(),
-        ),
+        )),
         creator_set_visibility: record.creator_set_visibility,
         is_user_upload: record.is_user_upload,
         is_intermediate_system_file: record.is_intermediate_system_file,
@@ -106,3 +112,86 @@ pub(super) fn build_user_media_file_response(args: UserMediaFileResponseArgs) ->
     })
     .collect::<Vec<_>>()
 }
+
+fn into_api_origin(origin: MediaFileOriginDetails) -> MediaFileOriginDetailsApi {
+  MediaFileOriginDetailsApi {
+    origin_category: origin.origin_category,
+    product_category: origin.product_category,
+    maybe_model: origin.maybe_model.map(|model| match model {
+      MediaFileModelDetails::SystemModel { model_type } => MediaFileModelDetailsApi::SystemModel { model_type },
+      MediaFileModelDetails::ModelWeight { model_type, token, title } => {
+        MediaFileModelDetailsApi::ModelWeight { model_type, token, title }
+      }
+    }),
+  }
+}
+
+fn into_api_cover_image(cover: MediaFileCoverImageDetails) -> LegacyMediaFileCoverImageDetails {
+  LegacyMediaFileCoverImageDetails {
+    maybe_cover_image_public_bucket_path: cover.maybe_cover_image_public_bucket_path,
+    maybe_cover_image_public_bucket_url: cover.maybe_cover_image_public_bucket_url,
+    maybe_links: cover.maybe_links.map(|links| CoverImageLinks {
+      cdn_url: links.cdn_url,
+      thumbnail_template: links.thumbnail_template,
+    }),
+    default_cover: MediaFileDefaultCover {
+      image_index: cover.default_cover.image_index,
+      color_index: cover.default_cover.color_index,
+    },
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use enums::by_table::media_files::media_file_origin_category::MediaFileOriginCategory;
+  use enums::by_table::media_files::media_file_origin_model_type::MediaFileOriginModelType;
+  use enums::by_table::media_files::media_file_origin_product_category::MediaFileOriginProductCategory;
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use super::*;
+
+  mod conversions {
+    use super::*;
+
+    #[test]
+    fn origin_details_preserve_system_and_user_models() {
+      for (model_type, model_token, model_title) in [
+        (None, None, None),
+        (Some(MediaFileOriginModelType::Tacotron2), None, None),
+        (Some(MediaFileOriginModelType::Tacotron2), Some("weight_fixture"), Some("Fixture model")),
+      ] {
+        let origin = MediaFileOriginDetails::from_db_fields_str(
+          MediaFileOriginCategory::Upload,
+          MediaFileOriginProductCategory::Unknown,
+          model_type,
+          model_token,
+          model_title,
+        );
+        let original = serde_json::to_value(&origin).unwrap();
+        let converted = serde_json::to_value(into_api_origin(origin)).unwrap();
+        assert_eq!(converted, original);
+        let decoded: MediaFileOriginDetailsApi = serde_json::from_value(converted).unwrap();
+        assert_eq!(serde_json::to_value(decoded).unwrap(), original);
+      }
+    }
+
+    #[test]
+    fn cover_details_preserve_legacy_fields_and_cdn_links() {
+      for maybe_hash in [None, Some("fixture_cover_hash")] {
+        let cover = MediaFileCoverImageDetails::from_optional_db_fields(
+          &MediaFileToken::new_from_str("m_fixture"),
+          MediaDomain::FakeYou,
+          ServerEnvironment::Production,
+          maybe_hash,
+          Some("image_"),
+          Some(".png"),
+        );
+        let original = serde_json::to_value(&cover).unwrap();
+        let converted = serde_json::to_value(into_api_cover_image(cover)).unwrap();
+        assert_eq!(converted, original);
+        let decoded: LegacyMediaFileCoverImageDetails = serde_json::from_value(converted).unwrap();
+        assert_eq!(serde_json::to_value(decoded).unwrap(), original);
+      }
+    }
+  }
+}

crates/service/web/storyteller_web/src/http_server/routes/application_routes/user_media_endpoint_tests.rs

@@ -7,6 +7,7 @@ use actix_web::body::MessageBody;
 use actix_web::dev::{Service, ServiceResponse};
 use actix_web::http::StatusCode;
 use actix_web::{test, web, App};
+use artcraft_api_defs::media_file::list::list_media_files_for_user_v2::ListMediaFilesForUserV2SuccessResponse;
 use mysql_testing::fixtures::media_files::create_test_video_media_file;
 use mysql_testing::fixtures::users::create_test_user;
 use mysql_testing::isolated::IsolatedTestDatabase;
@@ -108,6 +109,11 @@ async fn user_media_endpoint_versions_preserve_legacy_contract() {
   assert_eq!(first_v2.as_object().unwrap().len(), 3);
   assert_eq!(first_v2["results"], legacy["results"]);
   assert_eq!(first_v2["pagination"], json!({"current": 0, "has_more": true}));
+  // A Rust API client can decode and re-encode the full response without
+  // dropping nested or deprecated fields from either endpoint's media items.
+  let typed_v2: ListMediaFilesForUserV2SuccessResponse = serde_json::from_value(first_v2.clone()).unwrap();
+  assert_eq!(typed_v2.results.len(), 25);
+  assert_eq!(serde_json::to_value(typed_v2).unwrap(), first_v2);
   let (_, last_v2) = get(&app, &format!("{v2}?include_user_uploads=true&page_index=1"), session).await;
   assert_eq!(last_v2["results"], last["results"]);
   assert_eq!(last_v2["pagination"], json!({"current": 1, "has_more": false}));