<h1 align="center">megalib</h1>

<p align="center">
  Rust SDK for MEGA.nz cloud storage.
</p>

<p align="center">
  <a href="https://crates.io/crates/megalib"><img src="https://img.shields.io/crates/v/megalib?style=for-the-badge&logo=rust&logoColor=white&label=crates.io&color=F59E0B" alt="Crates.io"></a>
  <a href="https://docs.rs/megalib"><img src="https://img.shields.io/docsrs/megalib?style=for-the-badge&logo=readthedocs&logoColor=white&label=docs.rs&color=3B82F6" alt="Documentation"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-8B5CF6?style=for-the-badge" alt="MIT License"></a>
  <a href="https://github.com/11philip22/megalib"><img src="https://img.shields.io/badge/github-megalib-22C55E?style=for-the-badge&logo=github&logoColor=white" alt="GitHub repository"></a>
</p>

<p align="center">
  <a href="#overview">Overview</a> · <a href="#capabilities">Capabilities</a> · <a href="#installation">Installation</a> · <a href="#quickstart">Quickstart</a> · <a href="#examples">Examples</a> · <a href="#api-notes">API Notes</a> · <a href="#resources">Resources</a>
</p>

## Overview

`megalib` is an async Rust client library for working with MEGA.nz accounts, files, folders, shares, and public links. It is built as a Rust port of the MEGA C++ SDK and exposes high-level `SessionHandle` APIs for authenticated account operations plus public-link helpers for unauthenticated downloads and folder browsing.

> [!NOTE]
> This is an unofficial client library and is not affiliated with, endorsed by, or supported by Mega Limited.

## Capabilities

- **Authentication and accounts**: login, proxy login, registration, email verification, password changes, session loading, account info, and quota lookup.
- **Cached node tree**: `fetch_nodes`, root discovery, children by handle, child lookup by name, descendant traversal, contact roots, and inshare/outshare queries.
- **Filesystem operations**: stat, create folder, move, rename, remove, export, and share operations through node-first APIs or explicit path-based compatibility aliases.
- **Transfers**: file upload/download, resumable upload/download examples, byte and reader uploads, progress callbacks, parallel transfer workers, and HTTP/HTTPS/SOCKS5 proxy support.
- **Public access**: parse MEGA links, inspect and download public files, export account files, and open public folders without logging in.
- **Optional previews**: compile with the `preview` feature and call `enable_previews(true)` to generate upload thumbnails for supported media.

## Installation

Add `megalib` and an async runtime to your `Cargo.toml`:

```toml
[dependencies]
megalib = "0.11.0"
tokio = { version = "1", features = ["full"] }
```

For upload thumbnail generation:

```toml
[dependencies]
megalib = { version = "0.11.0", features = ["preview"] }
tokio = { version = "1", features = ["full"] }
```

## Quickstart

Log in, populate the cached node tree, and list the Cloud Drive root:

```rust
use megalib::{NodeType, SessionHandle};

#[tokio::main]
async fn main() -> megalib::Result<()> {
    let session = SessionHandle::login("user@example.com", "password").await?;
    session.fetch_nodes().await?;

    let root = session
        .root_nodes()
        .await?
        .into_iter()
        .find(|node| node.node_type == NodeType::Root)
        .expect("missing Cloud Drive root");

    for node in session.children_by_handle(&root.handle).await? {
        println!("{} ({:?})", node.name, node.node_type);
    }

    if let Some(documents) = session.child_node_by_name(&root, "Documents").await? {
        println!("Documents handle: {}", documents.handle);
    }

    Ok(())
}
```

> [!TIP]
> New code should prefer node-first APIs after `fetch_nodes()`. Path-based helpers are still available as explicit compatibility aliases such as `list_by_path`, `stat_by_path`, `mkdir_by_path`, `mv_by_path`, `rename_by_path`, `rm_by_path`, `upload_by_path`, `upload_resumable_by_path`, `export_by_path`, and `share_folder_by_path`.

## Examples

Each example is a runnable binary under `examples/`. Use `--help` to inspect the exact flags for any example:

```bash
cargo run --example login -- --help
```

Common workflows:

```bash
# Authentication and browsing
cargo run --example login -- --email you@example.com --password "your-password"
cargo run --example node_api -- --email you@example.com --password "your-password"
cargo run --example ls -- --email you@example.com --password "your-password" --path /Root
cargo run --example cached_session -- --email you@example.com --password "your-password"

# Upload and download
cargo run --example upload -- --email you@example.com --password "your-password" ./local-file.txt /Root
cargo run --example download -- --email you@example.com --password "your-password" /Root/remote-file.txt ./downloaded-file.txt
cargo run --example upload_resume -- --email you@example.com --password "your-password" ./large-file.bin /Root
cargo run --example download_resume -- --email you@example.com --password "your-password" /Root/large-file.bin ./large-file.bin

# Filesystem operations
cargo run --example stat -- --email you@example.com --password "your-password" --path /Root/file.txt
cargo run --example mkdir -- --email you@example.com --password "your-password" /Root/new-folder
cargo run --example rename -- --email you@example.com --password "your-password" /Root/file.txt file-renamed.txt
cargo run --example mv -- --email you@example.com --password "your-password" /Root/file.txt /Root/destination-folder
cargo run --example rm -- --email you@example.com --password "your-password" /Root/old-file.txt

# Sharing and public links
cargo run --example export -- --email you@example.com --password "your-password" --path /Root/file.txt
cargo run --example share -- --email you@example.com --password "your-password" --folder /Root/shared --recipient friend@example.com --level 0
cargo run --example folder -- "https://mega.nz/folder/<FOLDER_ID>#<KEY>"
cargo run --example download_public -- "https://mega.nz/file/<FILE_ID>#<KEY>" ./public-file.bin

# Account management
cargo run --example register -- --email you@example.com --password "your-password" --name "Your Name"
cargo run --example verify -- --state "SESSION_KEY_FROM_STEP_1" --link "CONFIRMATION_LINK_OR_FRAGMENT"
cargo run --example passwd -- --email you@example.com --password "current-password" --new "new-password"
```

Authenticated examples that define `--proxy` accept proxy URLs such as `http://proxy:8080` or `socks5://proxy:1080`.

## API Notes

- `SessionHandle::fetch_nodes()` populates the cached tree used by node-first APIs and path compatibility aliases.
- Cloud Drive paths are rooted at `/Root`; public folder paths are rooted at the shared folder name.
- Deprecated path-first canonical names remain for compatibility, but new code should use the explicit `*_by_path` aliases or node-first methods.
- Public file helpers in `megalib::public` can inspect and download MEGA links without an authenticated session.
- Video thumbnails with the `preview` feature require `ffmpegthumbnailer` to be installed and available on `PATH`.

## Resources

- [API documentation](https://docs.rs/megalib)
- [Crate package](https://crates.io/crates/megalib)
- [Repository](https://github.com/11philip22/megalib)
