# immich-sdk

A modern Rust SDK for the [Immich](https://immich.app/) photo and video management server.

## Features

- **Async-first**: Built on `tokio` and `reqwest` for modern async Rust
- **Builder pattern**: Ergonomic API with fluent builders
- **Type-safe**: Strongly typed models
- **Error handling**: Comprehensive error types with `thiserror`
- **Rustls TLS**: Uses rustls instead of OpenSSL

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
immich-sdk = "1.137"
```

## Quick Start

```rust
use immich_sdk::{Client, error::Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client
    let client = Client::from_url("https://immich.example.com")?
        .with_api_key("your-api-key");

    // List albums
    let albums = client.albums().list().execute().await?;
    println!("Found {} albums", albums.len());

    // Upload an asset
    let asset = client
        .assets()
        .upload()
        .file("/path/to/photo.jpg")
        .device_asset_id("phone-123")
        .device_id("my-device")
        .execute()
        .await?;

    println!("Uploaded asset: {:?}", asset.id);

    Ok(())
}
```

## Authentication

The SDK supports API key authentication:

```rust
use immich_sdk::Client;

let client = Client::from_url("https://immich.example.com")?
    .with_api_key("your-api-key-here");
```

## API Modules

### Assets

Upload, download, and manage photos and videos:

```rust
// List all assets
let assets = client.assets().list().execute().await?;

// Get a specific asset
let asset = client.assets().get(asset_id).execute().await?;

// Upload a new asset
let uploaded = client
    .assets()
    .upload()
    .file("/path/to/photo.jpg")
    .device_asset_id("unique-device-id")
    .device_id("device-name")
    .favorite()
    .execute()
    .await?;

// Delete assets
client
    .assets()
    .delete()
    .id(asset_id)
    .execute()
    .await?;
```

### Albums

Create and manage albums:

```rust
// Create an album
let album = client
    .albums()
    .create()
    .name("My Vacation")
    .execute()
    .await?;

// Add assets to album
client
    .albums()
    .add_assets(album.id)
    .asset_ids(vec![asset_id1, asset_id2])
    .execute()
    .await?;

// List all albums
let albums = client.albums().list().execute().await?;
```

### Server Info

Get server information:

```rust
// Get server version
let version = client.server().version().await?;
println!("Server version: {}", version);

// Get server features
let features = client.server().features().await?;
println!("OAuth enabled: {}", features.oauth);

// Ping the server
let pong = client.server().ping().await?;
println!("Ping: {}", pong);
```

## Error Handling

The SDK uses the `ImmichError` type for all errors:

```rust
use immich_sdk::error::ImmichError;

match client.assets().get(asset_id).execute().await {
    Ok(asset) => println!("Found: {:?}", asset),
    Err(ImmichError::NotFound(_)) => println!("Asset not found"),
    Err(ImmichError::Authentication(_)) => println!("Auth failed"),
    Err(e) => println!("Error: {}", e),
}
```

## Configuration

Create a client with custom configuration:

```rust
use immich_sdk::{Client, Config};
use std::time::Duration;

let config = Config::new("https://immich.example.com")
    .with_api_key("your-api-key")
    .with_timeout(Duration::from_secs(60));

let client = Client::new(config)?;
```

## License

This project is licensed under the MIT OR Apache-2.0 license.

## Contributing

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

## Acknowledgments

- [Immich](https://immich.app/) - The amazing photo and video management solution