openai-tools 1.1.0

//! OpenAI Files API Request Module
//!
//! This module provides the functionality to interact with the OpenAI Files API.
//! It allows you to upload, list, retrieve, delete files, and get file content.
//!
//! # Key Features
//!
//! - **Upload Files**: Upload files for fine-tuning, batch processing, assistants, etc.
//! - **List Files**: Retrieve all uploaded files
//! - **Retrieve File**: Get details of a specific file
//! - **Delete File**: Remove an uploaded file
//! - **Get Content**: Retrieve the content of a file
//!
//! # Quick Start
//!
//! ```rust,no_run
//! use openai_tools::files::request::{Files, FilePurpose};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let files = Files::new()?;
//!
//!     // List all files
//!     let response = files.list(None).await?;
//!     for file in &response.data {
//!         println!("{}: {} bytes", file.filename, file.bytes);
//!     }
//!
//!     Ok(())
//! }
//! ```

use crate::common::auth::{AuthProvider, OpenAIAuth};
use crate::common::client::create_http_client;
use crate::common::errors::{ErrorResponse, OpenAIToolError, Result};
use crate::files::response::{DeleteResponse, File, FileListResponse};
use request::multipart::{Form, Part};
use serde::{Deserialize, Serialize};
use std::path::Path;
use std::time::Duration;

/// Default API path for Files
const FILES_PATH: &str = "files";

/// The intended purpose of the uploaded file.
///
/// Different purposes have different processing requirements and usage patterns.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FilePurpose {
    /// For use with Assistants and Message files
    Assistants,
    /// For files generated by Assistants
    AssistantsOutput,
    /// For use with Batch API
    Batch,
    /// For files generated by Batch API
    BatchOutput,
    /// For use with Fine-tuning
    FineTune,
    /// For files generated by Fine-tuning
    FineTuneResults,
    /// For use with Vision features
    Vision,
    /// For user-uploaded data
    UserData,
}

impl FilePurpose {
    /// Returns the string representation of the purpose.
    pub fn as_str(&self) -> &'static str {
        match self {
            FilePurpose::Assistants => "assistants",
            FilePurpose::AssistantsOutput => "assistants_output",
            FilePurpose::Batch => "batch",
            FilePurpose::BatchOutput => "batch_output",
            FilePurpose::FineTune => "fine-tune",
            FilePurpose::FineTuneResults => "fine-tune-results",
            FilePurpose::Vision => "vision",
            FilePurpose::UserData => "user_data",
        }
    }
}

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

/// Client for interacting with the OpenAI Files API.
///
/// This struct provides methods to upload, list, retrieve, delete files,
/// and get file content. Use [`Files::new()`] to create a new instance.
///
/// # Providers
///
/// The client supports two providers:
/// - **OpenAI**: Standard OpenAI API (default)
/// - **Azure**: Azure OpenAI Service
///
/// # Example
///
/// ```rust,no_run
/// use openai_tools::files::request::{Files, FilePurpose};
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     let files = Files::new()?;
///
///     // Upload a file for fine-tuning
///     let file = files.upload_path("training_data.jsonl", FilePurpose::FineTune).await?;
///     println!("Uploaded: {} ({})", file.filename, file.id);
///
///     Ok(())
/// }
/// ```
pub struct Files {
    /// Authentication provider (OpenAI or Azure)
    auth: AuthProvider,
    /// Optional request timeout duration
    timeout: Option<Duration>,
}

impl Files {
    /// Creates a new Files client for OpenAI API.
    ///
    /// Initializes the client by loading the OpenAI API key from
    /// the environment variable `OPENAI_API_KEY`. Supports `.env` file loading
    /// via dotenvy.
    ///
    /// # Returns
    ///
    /// * `Ok(Files)` - A new Files client ready for use
    /// * `Err(OpenAIToolError)` - If the API key is not found in the environment
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::Files;
    ///
    /// let files = Files::new().expect("API key should be set");
    /// ```
    pub fn new() -> Result<Self> {
        let auth = AuthProvider::openai_from_env()?;
        Ok(Self { auth, timeout: None })
    }

    /// Creates a new Files client with a custom authentication provider
    pub fn with_auth(auth: AuthProvider) -> Self {
        Self { auth, timeout: None }
    }

    /// Creates a new Files client for Azure OpenAI API
    pub fn azure() -> Result<Self> {
        let auth = AuthProvider::azure_from_env()?;
        Ok(Self { auth, timeout: None })
    }

    /// Creates a new Files client by auto-detecting the provider
    pub fn detect_provider() -> Result<Self> {
        let auth = AuthProvider::from_env()?;
        Ok(Self { auth, timeout: None })
    }

    /// Creates a new Files client with URL-based provider detection
    pub fn with_url<S: Into<String>>(base_url: S, api_key: S) -> Self {
        let auth = AuthProvider::from_url_with_key(base_url, api_key);
        Self { auth, timeout: None }
    }

    /// Creates a new Files client from URL using environment variables
    pub fn from_url<S: Into<String>>(url: S) -> Result<Self> {
        let auth = AuthProvider::from_url(url)?;
        Ok(Self { auth, timeout: None })
    }

    /// Returns the authentication provider
    pub fn auth(&self) -> &AuthProvider {
        &self.auth
    }

    /// Sets a custom API endpoint URL (OpenAI only)
    ///
    /// Use this to point to alternative OpenAI-compatible APIs.
    ///
    /// # Arguments
    ///
    /// * `url` - The base URL (e.g., "https://my-proxy.example.com/v1")
    ///
    /// # Returns
    ///
    /// A mutable reference to self for method chaining
    pub fn base_url<T: AsRef<str>>(&mut self, url: T) -> &mut Self {
        if let AuthProvider::OpenAI(ref openai_auth) = self.auth {
            let new_auth = OpenAIAuth::new(openai_auth.api_key()).with_base_url(url.as_ref());
            self.auth = AuthProvider::OpenAI(new_auth);
        } else {
            tracing::warn!("base_url() is only supported for OpenAI provider. Use azure() or with_auth() for Azure.");
        }
        self
    }

    /// Sets the request timeout duration.
    ///
    /// # Arguments
    ///
    /// * `timeout` - The maximum time to wait for a response
    ///
    /// # Returns
    ///
    /// A mutable reference to self for method chaining
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::time::Duration;
    /// use openai_tools::files::request::Files;
    ///
    /// let mut files = Files::new().unwrap();
    /// files.timeout(Duration::from_secs(120));  // Longer timeout for file uploads
    /// ```
    pub fn timeout(&mut self, timeout: Duration) -> &mut Self {
        self.timeout = Some(timeout);
        self
    }

    /// Creates the HTTP client with default headers.
    fn create_client(&self) -> Result<(request::Client, request::header::HeaderMap)> {
        let client = create_http_client(self.timeout)?;
        let mut headers = request::header::HeaderMap::new();
        self.auth.apply_headers(&mut headers)?;
        headers.insert("User-Agent", request::header::HeaderValue::from_static("openai-tools-rust"));
        Ok((client, headers))
    }

    /// Uploads a file from a file path.
    ///
    /// The file will be uploaded with the specified purpose.
    /// Individual files can be up to 512 MB, and the total size of all files
    /// uploaded by one organization can be up to 100 GB.
    ///
    /// # Arguments
    ///
    /// * `file_path` - Path to the file to upload
    /// * `purpose` - The intended purpose of the uploaded file
    ///
    /// # Returns
    ///
    /// * `Ok(File)` - The uploaded file object
    /// * `Err(OpenAIToolError)` - If the file cannot be read or the upload fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::{Files, FilePurpose};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///     let file = files.upload_path("data.jsonl", FilePurpose::FineTune).await?;
    ///     println!("Uploaded: {}", file.id);
    ///     Ok(())
    /// }
    /// ```
    pub async fn upload_path(&self, file_path: &str, purpose: FilePurpose) -> Result<File> {
        let path = Path::new(file_path);
        let filename = path.file_name().and_then(|n| n.to_str()).unwrap_or("file").to_string();

        let content = tokio::fs::read(file_path).await.map_err(|e| OpenAIToolError::Error(format!("Failed to read file: {}", e)))?;

        self.upload_bytes(&content, &filename, purpose).await
    }

    /// Uploads a file from bytes.
    ///
    /// The file will be uploaded with the specified filename and purpose.
    ///
    /// # Arguments
    ///
    /// * `content` - The file content as bytes
    /// * `filename` - The name to give the file
    /// * `purpose` - The intended purpose of the uploaded file
    ///
    /// # Returns
    ///
    /// * `Ok(File)` - The uploaded file object
    /// * `Err(OpenAIToolError)` - If the upload fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::{Files, FilePurpose};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///
    ///     let content = b"{\"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}";
    ///     let file = files.upload_bytes(content, "training.jsonl", FilePurpose::FineTune).await?;
    ///
    ///     println!("Uploaded: {}", file.id);
    ///     Ok(())
    /// }
    /// ```
    pub async fn upload_bytes(&self, content: &[u8], filename: &str, purpose: FilePurpose) -> Result<File> {
        let (client, headers) = self.create_client()?;

        let file_part = Part::bytes(content.to_vec())
            .file_name(filename.to_string())
            .mime_str("application/octet-stream")
            .map_err(|e| OpenAIToolError::Error(format!("Failed to set MIME type: {}", e)))?;

        let form = Form::new().part("file", file_part).text("purpose", purpose.as_str().to_string());

        let endpoint = self.auth.endpoint(FILES_PATH);
        let response = client.post(&endpoint).headers(headers).multipart(form).send().await.map_err(OpenAIToolError::RequestError)?;

        let status = response.status();
        let content = response.text().await.map_err(OpenAIToolError::RequestError)?;

        if cfg!(test) {
            tracing::info!("Response content: {}", content);
        }

        if !status.is_success() {
            if let Ok(error_resp) = serde_json::from_str::<ErrorResponse>(&content) {
                return Err(OpenAIToolError::Error(error_resp.error.message.unwrap_or_default()));
            }
            return Err(OpenAIToolError::Error(format!("API error ({}): {}", status, content)));
        }

        serde_json::from_str::<File>(&content).map_err(OpenAIToolError::SerdeJsonError)
    }

    /// Lists all files that belong to the user's organization.
    ///
    /// Optionally filter by purpose.
    ///
    /// # Arguments
    ///
    /// * `purpose` - Optional filter by file purpose
    ///
    /// # Returns
    ///
    /// * `Ok(FileListResponse)` - The list of files
    /// * `Err(OpenAIToolError)` - If the request fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::{Files, FilePurpose};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///
    ///     // List all files
    ///     let all_files = files.list(None).await?;
    ///     println!("Total files: {}", all_files.data.len());
    ///
    ///     // List only fine-tuning files
    ///     let ft_files = files.list(Some(FilePurpose::FineTune)).await?;
    ///     println!("Fine-tuning files: {}", ft_files.data.len());
    ///
    ///     Ok(())
    /// }
    /// ```
    pub async fn list(&self, purpose: Option<FilePurpose>) -> Result<FileListResponse> {
        let (client, headers) = self.create_client()?;

        let endpoint = self.auth.endpoint(FILES_PATH);
        let url = match purpose {
            Some(p) => format!("{}?purpose={}", endpoint, p.as_str()),
            None => endpoint,
        };

        let response = client.get(&url).headers(headers).send().await.map_err(OpenAIToolError::RequestError)?;

        let status = response.status();
        let content = response.text().await.map_err(OpenAIToolError::RequestError)?;

        if cfg!(test) {
            tracing::info!("Response content: {}", content);
        }

        if !status.is_success() {
            if let Ok(error_resp) = serde_json::from_str::<ErrorResponse>(&content) {
                return Err(OpenAIToolError::Error(error_resp.error.message.unwrap_or_default()));
            }
            return Err(OpenAIToolError::Error(format!("API error ({}): {}", status, content)));
        }

        serde_json::from_str::<FileListResponse>(&content).map_err(OpenAIToolError::SerdeJsonError)
    }

    /// Retrieves details of a specific file.
    ///
    /// # Arguments
    ///
    /// * `file_id` - The ID of the file to retrieve
    ///
    /// # Returns
    ///
    /// * `Ok(File)` - The file details
    /// * `Err(OpenAIToolError)` - If the file is not found or the request fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::Files;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///     let file = files.retrieve("file-abc123").await?;
    ///
    ///     println!("File: {}", file.filename);
    ///     println!("Size: {} bytes", file.bytes);
    ///     println!("Purpose: {}", file.purpose);
    ///     Ok(())
    /// }
    /// ```
    pub async fn retrieve(&self, file_id: &str) -> Result<File> {
        let (client, headers) = self.create_client()?;
        let url = format!("{}/{}", self.auth.endpoint(FILES_PATH), file_id);

        let response = client.get(&url).headers(headers).send().await.map_err(OpenAIToolError::RequestError)?;

        let status = response.status();
        let content = response.text().await.map_err(OpenAIToolError::RequestError)?;

        if cfg!(test) {
            tracing::info!("Response content: {}", content);
        }

        if !status.is_success() {
            if let Ok(error_resp) = serde_json::from_str::<ErrorResponse>(&content) {
                return Err(OpenAIToolError::Error(error_resp.error.message.unwrap_or_default()));
            }
            return Err(OpenAIToolError::Error(format!("API error ({}): {}", status, content)));
        }

        serde_json::from_str::<File>(&content).map_err(OpenAIToolError::SerdeJsonError)
    }

    /// Deletes a file.
    ///
    /// # Arguments
    ///
    /// * `file_id` - The ID of the file to delete
    ///
    /// # Returns
    ///
    /// * `Ok(DeleteResponse)` - Confirmation of deletion
    /// * `Err(OpenAIToolError)` - If the file cannot be deleted or the request fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::Files;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///     let result = files.delete("file-abc123").await?;
    ///
    ///     if result.deleted {
    ///         println!("File {} was deleted", result.id);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub async fn delete(&self, file_id: &str) -> Result<DeleteResponse> {
        let (client, headers) = self.create_client()?;
        let url = format!("{}/{}", self.auth.endpoint(FILES_PATH), file_id);

        let response = client.delete(&url).headers(headers).send().await.map_err(OpenAIToolError::RequestError)?;

        let status = response.status();
        let content = response.text().await.map_err(OpenAIToolError::RequestError)?;

        if cfg!(test) {
            tracing::info!("Response content: {}", content);
        }

        if !status.is_success() {
            if let Ok(error_resp) = serde_json::from_str::<ErrorResponse>(&content) {
                return Err(OpenAIToolError::Error(error_resp.error.message.unwrap_or_default()));
            }
            return Err(OpenAIToolError::Error(format!("API error ({}): {}", status, content)));
        }

        serde_json::from_str::<DeleteResponse>(&content).map_err(OpenAIToolError::SerdeJsonError)
    }

    /// Retrieves the content of a file.
    ///
    /// # Arguments
    ///
    /// * `file_id` - The ID of the file to retrieve content from
    ///
    /// # Returns
    ///
    /// * `Ok(Vec<u8>)` - The file content as bytes
    /// * `Err(OpenAIToolError)` - If the file cannot be retrieved or the request fails
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use openai_tools::files::request::Files;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let files = Files::new()?;
    ///     let content = files.content("file-abc123").await?;
    ///
    ///     // Convert to string if it's text content
    ///     let text = String::from_utf8(content)?;
    ///     println!("Content: {}", text);
    ///     Ok(())
    /// }
    /// ```
    pub async fn content(&self, file_id: &str) -> Result<Vec<u8>> {
        let (client, headers) = self.create_client()?;
        let url = format!("{}/{}/content", self.auth.endpoint(FILES_PATH), file_id);

        let response = client.get(&url).headers(headers).send().await.map_err(OpenAIToolError::RequestError)?;

        let bytes = response.bytes().await.map_err(OpenAIToolError::RequestError)?;

        Ok(bytes.to_vec())
    }
}