cloudreve-api

A Rust library for interacting with the Cloudreve API. This library provides asynchronous access to all major Cloudreve API endpoints with proper error handling and type safety.

Features

• ✨ Full async/await support with Tokio
• 🔐 Complete authentication flow (login, token refresh, 2FA)
• 📁 Comprehensive file operations (upload, download, list, delete, move, copy)
• 🔗 Share link management
• 👤 User and storage management
• 🎯 Type-safe request and response structures
• 🛡️ Built-in error handling
• 📦 Support for both Cloudreve v3 and v4 APIs

Installation

Add this to your Cargo.toml:

[dependencies]
cloudreve-api = "0.3"
tokio = { version = "1", features = ["full"] }

Or use cargo-edit:

cargo add cloudreve-api

Quick Start

Basic Setup

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client instance (auto-detects API version)
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;

    // Login
    api.login("user@example.com", "password").await?;

    println!("Successfully logged in!");
    Ok(())
}

File Operations

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;
    api.login("user@example.com", "password").await?;

    // List files in a directory
    let files = api.list_files("/").await?;
    println!("Found {} items", files.total_count());

    for item in files.items() {
        if item.is_folder {
            println!("  📁 {}/", item.name);
        } else {
            println!("  📄 {} ({} bytes)", item.name, item.size);
        }
    }

    Ok(())
}

Create Directory

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;
    api.login("user@example.com", "password").await?;

    // Create a new directory
    api.create_directory("/photos/vacation").await?;

    println!("Directory created successfully!");
    Ok(())
}

Upload a File

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;
    api.login("user@example.com", "password").await?;

    // Upload a file
    let content = b"Hello, World!".to_vec();
    api.upload_file("/hello.txt", content, None).await?;

    println!("File uploaded successfully!");
    Ok(())
}

Download a File

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;
    api.login("user@example.com", "password").await?;

    // Get download URL
    let url = api.download_file("/document.pdf").await?;
    println!("Download URL: {}", url);

    Ok(())
}

Share Management

use cloudreve_api::{CloudreveAPI, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await?;
    api.login("user@example.com", "password").await?;

    // List shares
    let shares = api.list_shares().await?;
    for share in shares {
        println!("Share key: {}", share.key);
    }

    Ok(())
}

API Coverage

Supported API Categories

• Authentication & Session

  • Login with email/password
  • Token management
  • 2FA support

• User Management

  • User profile
  • Storage capacity
  • Storage policies
  • Settings management

• File Operations

  • List files/directories
  • Upload (with chunked support)
  • Download
  • Create directory
  • Rename
  • Move
  • Copy
  • Delete
  • Get file info

• Sharing

  • Create share links
  • List share links
  • Update share links
  • Delete share links

• Advanced Features

  • File search
  • Thumbnail generation
  • Archive operations
  • WebDAV account management

API Versions

This library supports both Cloudreve v3 and v4 APIs with automatic version detection:

use cloudreve_api::{CloudreveAPI, ApiVersion, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Auto-detect version
    let api = CloudreveAPI::new("https://instance.com").await?;

    // Or specify version explicitly
    let api = CloudreveAPI::with_version("https://instance.com", ApiVersion::V4)?;

    Ok(())
}

Error Handling

All API calls return a Result<T, Error> type:

use cloudreve_api::{CloudreveAPI, Error};

#[tokio::main]
async fn main() {
    let mut api = CloudreveAPI::new("https://your-cloudreve-instance.com").await.unwrap();

    match api.login("user@example.com", "wrong_password").await {
        Ok(_) => println!("Login successful"),
        Err(Error::Api { code, message }) => {
            eprintln!("API Error {}: {}", code, message);
        }
        Err(Error::Http(err)) => {
            eprintln!("HTTP Error: {}", err);
        }
        Err(err) => {
            eprintln!("Other Error: {}", err);
        }
    }
}

Error Types

• Error::Http - Network/HTTP related errors
• Error::Json - Serialization/deserialization errors
• Error::Api - API error responses with code and message
• Error::Reqwest - Underlying reqwest errors
• Error::Url - URL parsing errors
• Error::InvalidResponse - Invalid API response format

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please file an issue.

Acknowledgments

• Built with Tokio for async runtime
• Uses Reqwest for HTTP requests
• Part of the Cloudreve ecosystem