halo_api 0.1.1

Unofficial Halo Infinite REST API client for Rust (CSR, service record, match history, and more).
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

# halo_api

[![CI](https://github.com/nuzzles/halo_api/actions/workflows/ci.yml/badge.svg)](https://github.com/nuzzles/halo_api/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/halo_api.svg)](https://crates.io/crates/halo_api)
[![docs.rs](https://docs.rs/halo_api/badge.svg)](https://docs.rs/halo_api)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

Unofficial Halo Infinite REST API client for Rust: CSR/rank lookups, service records, match history, and more.

> [!IMPORTANT]
> This is an unofficial, community-maintained library. It is not affiliated with, endorsed by Microsoft.

## What this crate does

- Separates authentication (`HaloAuthClient`) from Halo API operations (`HaloInfiniteClient`).
- Acquires and caches both the Spartan token and Waypoint flight clearance.
- Covers stats, skill, profile, UGC, progression, career rank, reward tracks, ban, and privacy endpoints.
- Filters service records by season, playlist, mode, and ranked/social via `ServiceRecordFilter`.
- Paces requests per Halo Waypoint origin (default 5/s) so bursts don't trip throttling; configure via
  `HaloInfiniteClient::builder()`.
- Automatically invalidates and retries once on an expired/unauthorized (401) response, instead of surfacing a
  hard failure the caller has to handle manually.

This crate depends on the [`xbox`](https://crates.io/crates/xbox) crate for Xbox Live authentication (XSTS
tickets and XUID resolution). [`HaloAuthClient`] acquires and refreshes all Halo Waypoint credentials.

If your application already obtains Halo Waypoint credentials, use
`HaloAuthClient::from_tokens(spartan_token, clearance_token)` instead. Those values remain private to the
client, but the caller is responsible for replacing the client when they expire.

## Quick start

```rust,no_run
use std::sync::Arc;

use halo_api::clients::hi::models::PlaylistId;
use halo_api::auth::HaloAuthClient;
use halo_api::clients::hi::{HaloInfiniteClient, Player};
use xbox::auth::LegacyPasswordProvider;
use xbox::XboxClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let xbox_client = Arc::new(XboxClient::new(LegacyPasswordProvider::new(
        "my-username",
        "my-password",
    )));
    let auth = HaloAuthClient::from_xbox_client(xbox_client.clone());
    let halo = HaloInfiniteClient::new(auth);

    let xuid = xbox_client.gamertag_to_xuid("Some Gamertag").await?;
    let csr = halo
        .playlist_csr(PlaylistId::RANKED_ARENA, &Player::from(&xuid))
        .await?;

    println!("{csr:?}");
    Ok(())
}
```

## MSRV

This crate has a [Minimum Supported Rust Version (MSRV)][MSRV] of 1.96.

[MSRV]: CHANGELOG.md

## License

Licensed under either of

- Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license
   ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option

## Contribution

See [CONTRIBUTING.md](CONTRIBUTING.md).

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.