comdirect-rest-api 0.2.1

High-availability Rust client for the comdirect REST API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# comdirect-rest-api

High-availability Rust client for the comdirect REST API.

This crate provides:

- Typed API access for `accounts` and `brokerage` endpoints
- Session lifecycle orchestration (`login`, `try_restore`, `shutdown`)
- Automatic token refresh with state and refresh-token callbacks
- Retry and infrastructure helpers for resilient API calls
- Optional web-based interactive TAN flow via the `web` feature

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
comdirect-rest-api = "0.2.0"
```

Enable web login routes when needed:

```toml
[dependencies]
comdirect-rest-api = { version = "0.2.0", features = ["web"] }
```

## Quick Start

### 1. Restore an existing session (recommended for services)

```rust
use comdirect_rest_api::{Session, SessionConfig};

async fn run() -> Result<(), comdirect_rest_api::ComdirectError> {
    let config = SessionConfig::new("client-id", "client-secret", "username", "pin")
        .with_base_url("https://api.comdirect.de")
        .with_request_timeout(std::time::Duration::from_secs(20))
        .with_refresh_buffer(std::time::Duration::from_secs(90));

    let session = Session::from_config(config)?;
    session.try_restore("persisted-refresh-token").await?;

    let balances = session.accounts().get_balances().await?;
    println!("{} accounts", balances.values.len());

    session.shutdown().await;
    Ok(())
}
```

### 2. Interactive login flow

```rust
use comdirect_rest_api::{Session, TanAction};
use std::io::{self, Write};

async fn run() -> Result<(), comdirect_rest_api::ComdirectError> {
    let session = Session::new("client-id", "client-secret", "username", "pin")?;

    session
        .set_refresh_token_callback(|refresh_token| {
            // Persist this token securely and use try_restore() on next startup.
            println!("new refresh token: {refresh_token}");
        })
        .await;

    session
        .login(|challenge| async move {
            println!("challenge {}", challenge.challenge_id);
            println!("Please approve the Push-TAN in the Comdirect app.");
            print!("Press Enter only after you have approved it... ");
            let _ = io::stdout().flush();
            let mut line = String::new();
            let _ = io::stdin().read_line(&mut line);
            TanAction::ConfirmPushTan
        })
        .await?;

    session.shutdown().await;
    Ok(())
}
```

Important: comdirect does not provide a redirect-based completion step for this TAN flow.
Your application callback must wait for an explicit user confirmation signal (for example a
frontend button like "I've allowed it") before returning `TanAction::ConfirmPushTan`.

## API Surface

Top-level modules:

- `session`: auth lifecycle, restore/login flow, refresh worker integration
- `accounts`: typed account endpoints (balances, single balance, transactions)
- `brokerage`: typed brokerage endpoints (depots, positions, instruments)
- `auth`, `types`, `error`: shared auth models, common types, and error handling
- `web` (feature-gated): mounts browser-driven auth routes for TAN workflows

## Optional Web Feature

When `web` is enabled, you can expose login routes with Axum.

- `Session::login_web(...)` mounts default auth routes under `/comdirect`
- `mount_session_login_route(...)` allows custom route mounting
- The callback must still wait for explicit user confirmation before submitting `ConfirmPushTan`

## Development

Run tests for this crate:

```bash
cargo test -p comdirect-rest-api
```

Run with optional web feature tests/build:

```bash
cargo test -p comdirect-rest-api --features web
```

## License

Licensed under either:

- MIT
- Apache-2.0

at your option.