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

cloudreve-api 0.3.1