xai_rust/models/

file.rs

//! File API types.

use serde::{Deserialize, Serialize};

/// A file object stored in the xAI API.
#[derive(Debug, Clone, Deserialize)]
pub struct FileObject {
    /// Unique identifier for the file.
    pub id: String,
    /// The name of the file.
    pub filename: String,
    /// The size of the file in bytes.
    pub bytes: u64,
    /// Unix timestamp of when the file was created.
    pub created_at: i64,
    /// The purpose of the file.
    pub purpose: String,
    /// Object type (always "file").
    #[serde(default)]
    pub object: String,
}

/// Response from listing files.
#[derive(Debug, Clone, Deserialize)]
pub struct FileListResponse {
    /// The list of files.
    pub data: Vec<FileObject>,
    /// Object type (always "list").
    #[serde(default)]
    pub object: String,
}

/// Purpose of an uploaded file.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FilePurpose {
    /// For use with assistants/chat.
    #[default]
    Assistants,
    /// For fine-tuning.
    FineTune,
    /// For batch operations.
    Batch,
}

impl FilePurpose {
    /// Get the string representation.
    ///
    /// Returns the same value as serde serialization (`snake_case`).
    pub fn as_str(&self) -> &'static str {
        match self {
            FilePurpose::Assistants => "assistants",
            FilePurpose::FineTune => "fine_tune",
            FilePurpose::Batch => "batch",
        }
    }
}

impl std::fmt::Display for FilePurpose {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// Delete file response.
#[derive(Debug, Clone, Deserialize)]
pub struct DeleteFileResponse {
    /// The ID of the deleted file.
    pub id: String,
    /// Whether the deletion was successful.
    pub deleted: bool,
    /// Object type.
    #[serde(default)]
    pub object: String,
}

/// Request payload for downloading a file through the explicit upload/download flow.
#[derive(Debug, Clone, Serialize)]
pub struct FileDownloadRequest {
    /// Identifier for the file to download.
    pub file_id: String,
}

/// Request payload for initializing multipart-style uploads.
#[derive(Debug, Clone, Serialize)]
pub struct FileUploadInitializeRequest {
    /// Name of the target file.
    pub filename: String,
    /// Target purpose.
    pub purpose: FilePurpose,
    /// Optional total size in bytes, if known.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total_size_bytes: Option<u64>,
}

impl FileUploadInitializeRequest {
    /// Create a new initialize request.
    pub fn new(filename: impl Into<String>, purpose: FilePurpose) -> Self {
        Self {
            filename: filename.into(),
            purpose,
            total_size_bytes: None,
        }
    }

    /// Set the total expected size.
    pub fn total_size_bytes(mut self, size: u64) -> Self {
        self.total_size_bytes = Some(size);
        self
    }
}

/// Response for upload initialization.
#[derive(Debug, Clone, Deserialize)]
pub struct FileUploadInitializeResponse {
    /// Upload session identifier.
    #[serde(default)]
    pub upload_id: String,
    /// Optional object type.
    #[serde(default)]
    pub object: String,
    /// Optional chunk size that should be used.
    #[serde(default)]
    pub chunk_size: Option<u64>,
    /// Optional upload session expiration timestamp.
    #[serde(default)]
    pub expires_at: Option<i64>,
}

/// Request payload for a file chunk upload.
#[derive(Debug, Clone, Serialize)]
pub struct FileUploadChunksRequest {
    /// Upload session identifier.
    pub upload_id: String,
    /// Chunk sequence index (1-based).
    pub part: u32,
    /// Base64 encoded chunk payload.
    pub chunk: String,
    /// Optional chunk checksum.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub checksum: Option<String>,
}

impl FileUploadChunksRequest {
    /// Create a new chunk upload request.
    pub fn new(upload_id: impl Into<String>, part: u32, chunk: impl Into<String>) -> Self {
        Self {
            upload_id: upload_id.into(),
            part,
            chunk: chunk.into(),
            checksum: None,
        }
    }

    /// Set optional checksum for the chunk.
    pub fn checksum(mut self, checksum: impl Into<String>) -> Self {
        self.checksum = Some(checksum.into());
        self
    }
}

/// Response for chunk upload.
#[derive(Debug, Clone, Deserialize)]
pub struct FileUploadChunksResponse {
    /// Upload session identifier.
    #[serde(default)]
    pub upload_id: String,
    /// Whether all chunks for the upload session are uploaded.
    #[serde(default)]
    pub complete: bool,
    /// Optional status message.
    #[serde(default)]
    pub status: Option<String>,
    /// Optional current chunk index.
    #[serde(default)]
    pub uploaded_part: Option<u32>,
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── FilePurpose serde roundtrips ───────────────────────────────────

    #[test]
    fn file_purpose_roundtrip_all_variants() {
        for (variant, expected) in [
            (FilePurpose::Assistants, "assistants"),
            (FilePurpose::FineTune, "fine_tune"),
            (FilePurpose::Batch, "batch"),
        ] {
            let json = serde_json::to_string(&variant).unwrap();
            assert_eq!(json, format!("\"{expected}\""));

            let back: FilePurpose = serde_json::from_str(&json).unwrap();
            assert_eq!(back, variant);
        }
    }

    #[test]
    fn file_purpose_as_str_matches_serde() {
        for variant in [
            FilePurpose::Assistants,
            FilePurpose::FineTune,
            FilePurpose::Batch,
        ] {
            let serde_str = serde_json::to_value(variant)
                .unwrap()
                .as_str()
                .unwrap()
                .to_string();
            assert_eq!(variant.as_str(), serde_str);
        }
    }

    #[test]
    fn file_purpose_display_matches_as_str() {
        for variant in [
            FilePurpose::Assistants,
            FilePurpose::FineTune,
            FilePurpose::Batch,
        ] {
            assert_eq!(format!("{variant}"), variant.as_str());
        }
    }

    #[test]
    fn file_purpose_default_is_assistants() {
        assert_eq!(FilePurpose::default(), FilePurpose::Assistants);
    }

    #[test]
    fn file_purpose_rejects_unknown() {
        let result = serde_json::from_str::<FilePurpose>(r#""unknown_purpose""#);
        assert!(result.is_err());
    }

    // ── FileObject deserialization ─────────────────────────────────────

    #[test]
    fn file_object_deserialize() {
        let json = serde_json::json!({
            "id": "file-abc",
            "filename": "test.txt",
            "bytes": 1024,
            "created_at": 1700000000,
            "purpose": "assistants",
            "object": "file"
        });
        let fo: FileObject = serde_json::from_value(json).unwrap();
        assert_eq!(fo.id, "file-abc");
        assert_eq!(fo.filename, "test.txt");
        assert_eq!(fo.bytes, 1024);
        assert_eq!(fo.purpose, "assistants");
    }

    #[test]
    fn file_object_object_field_defaults() {
        let json = serde_json::json!({
            "id": "file-abc",
            "filename": "test.txt",
            "bytes": 0,
            "created_at": 0,
            "purpose": "batch"
        });
        let fo: FileObject = serde_json::from_value(json).unwrap();
        assert_eq!(fo.object, ""); // default for missing field
    }

    // ── DeleteFileResponse ─────────────────────────────────────────────

    #[test]
    fn delete_file_response_deserialize() {
        let json = serde_json::json!({
            "id": "file-xyz",
            "deleted": true,
            "object": "file"
        });
        let resp: DeleteFileResponse = serde_json::from_value(json).unwrap();
        assert_eq!(resp.id, "file-xyz");
        assert!(resp.deleted);
    }

    // ── FileListResponse ───────────────────────────────────────────────

    #[test]
    fn file_list_response_deserialize() {
        let json = serde_json::json!({
            "data": [{
                "id": "file-1",
                "filename": "a.txt",
                "bytes": 100,
                "created_at": 0,
                "purpose": "assistants"
            }],
            "object": "list"
        });
        let list: FileListResponse = serde_json::from_value(json).unwrap();
        assert_eq!(list.data.len(), 1);
        assert_eq!(list.data[0].id, "file-1");
    }

    #[test]
    fn file_upload_initialize_request_roundtrip() {
        let request = FileUploadInitializeRequest::new("video.mp4", FilePurpose::FineTune)
            .total_size_bytes(12345);
        let json = serde_json::to_value(&request).unwrap();
        assert_eq!(json["filename"], "video.mp4");
        assert_eq!(json["purpose"], "fine_tune");
        assert_eq!(json["total_size_bytes"], 12345);
    }

    #[test]
    fn file_upload_chunks_request_roundtrip() {
        let request = FileUploadChunksRequest::new("upload-1", 2, "YQ==").checksum("abc");
        let json = serde_json::to_value(&request).unwrap();
        assert_eq!(json["upload_id"], "upload-1");
        assert_eq!(json["part"], 2);
        assert_eq!(json["chunk"], "YQ==");
        assert_eq!(json["checksum"], "abc");
    }

    #[test]
    fn file_upload_chunks_response_deserialize() {
        let json = serde_json::json!({
            "upload_id": "upload-1",
            "complete": true,
            "status": "complete",
            "uploaded_part": 2,
        });
        let response: FileUploadChunksResponse = serde_json::from_value(json).unwrap();
        assert_eq!(response.upload_id, "upload-1");
        assert!(response.complete);
        assert_eq!(response.uploaded_part, Some(2));
    }
}