# lunchflow

Rust client library and CLI for the [LunchFlow API](https://docs.lunchflow.app/api-reference/introduction).

## Installation

### As a library

```toml
[dependencies]
lunchflow = "0.1"
```

### As a CLI

```
cargo install lunchflow --features cli
```

## Library usage

```rust
use lunchflow::{LunchFlowClient, TransactionParams};

#[tokio::main]
async fn main() -> lunchflow::Result<()> {
    let client = LunchFlowClient::new("your-api-key")?;

    // List accounts
    let accounts = client.list_accounts().await?;

    // Get balance
    let balance = client.get_balance(accounts[0].id).await?;
    println!("{} {:.2}", balance.currency, balance.amount);

    // Get transactions
    let txns = client.get_transactions(
        accounts[0].id,
        TransactionParams {
            include_pending: true,
            from: Some("2025-01-01".to_string()),
            to: Some("2025-03-31".to_string()),
        },
    ).await?;

    // Get holdings (brokerage accounts only)
    let holdings = client.get_holdings(accounts[0].id).await?;

    Ok(())
}
```

### Error handling

```rust
use lunchflow::Error;

match client.get_balance(id).await {
    Ok(b) => println!("{:.2} {}", b.amount, b.currency),
    Err(Error::NotFound(_)) => eprintln!("account not found"),
    Err(Error::HoldingsNotSupported) => eprintln!("not a brokerage account"),
    Err(Error::Forbidden) => eprintln!("invalid API key or inactive subscription"),
    Err(e) => eprintln!("error: {e}"),
}
```

## CLI usage

Set your API key via flag or environment variable:

```
export LUNCHFLOW_API_KEY=your-api-key
```

### Commands

```
# List all accounts
lunchflow accounts

# Get balance for an account
lunchflow balance <account-id>

# Get transactions (all options are optional)
lunchflow transactions <account-id> [--pending] [--from YYYY-MM-DD] [--to YYYY-MM-DD]

# Get holdings (brokerage accounts only)
lunchflow holdings <account-id>
```

## API coverage

| Endpoint | Method | Implemented |
|---|---|---|
| List accounts | `GET /accounts` | ✓ |
| Get balance | `GET /accounts/{id}/balance` | ✓ |
| Get transactions | `GET /accounts/{id}/transactions` | ✓ |
| Get holdings | `GET /accounts/{id}/holdings` | ✓ |

## Release

Pushing a `v*` tag triggers the release workflow, which publishes to crates.io. Requires a `CARGO_REGISTRY_TOKEN` secret in the repository settings.

```
git tag v0.1.0 && git push origin v0.1.0
```
