torn-api 1.7.7

<h1 align="center">torn-api.rs</h1>
<div align="center">
 <strong>
   Rust Torn API bindings
 </strong>
</div>

<br />

<div align="center">
  <!-- Version -->
  <a href="https://crates.io/crates/torn-api">
    <img src="https://img.shields.io/crates/v/torn-api.svg?style=flat-square"
    alt="Crates.io version" /></a>
  <!-- Docs -->
  <a href="https://docs.rs/torn-api">
    <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" />
  </a>
  <!-- License -->
  <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" />
</div>

<br />

Async and typesafe bindings for the [Torn API](https://www.torn.com/swagger.php) that are auto-generated based on the v2 OpenAPI spec.

## Installation
torn-api requires an async runtime such as [tokio](https://github.com/tokio-rs/tokio) or [smol](https://github.com/smol-rs/smol) in order to function. It *should* be fully runtime agnostic when the `reqwest` feature is disabled.
```toml
[dependencies]
torn-api = "1.7"
```

### Features
- `reqwest`: Include an implementation of the client which uses the [reqwest](https://github.com/seanmonstar/reqwest) crate as its HTTP client. Requires tokio runtime.
- `models`: Generate response and parameter model definitions.
- `requests`: Generate requests model definitions.
- `scopes`: Generate scope objects which group endpoints by category.
- `builder`: Generate builders using [bon](https://github.com/elastio/bon) for all request structs.
- `strum`: Derive [EnumIs](https://docs.rs/strum/latest/strum/derive.EnumIs.html) and [EnumTryAs](https://docs.rs/strum/latest/strum/derive.EnumTryAs.html) for all auto-generated enums.

## Quickstart

```rust
use torn_api::{executor::{ReqwestClient, ExecutorExt}, models::RacingRaceTypeEnum};

let client = ReqwestClient::new("XXXXXXXXXXXXX");

let response = client.user().races(|r| r.cat(RacingRaceTypeEnum::Official)).await.unwrap();

let race = &response.races[0];

println!("Race '{}': winner was {}", race.title, race.results[0].driver_id);
```

### Use with undocumented endpoints
The v2 API exposes v1 endpoints as undocumented endpoints in cases where they haven't been ported over yet. It is still possible (though not recommended) to use this crate with such endpoints by manually implementing the [`IntoRequest`](https://docs.rs/torn-api/latest/torn_api/request/trait.IntoRequest.html) trait.


```rust
use torn_api::{
    executor::{ReqwestClient, Executor}, 
    models::UserId,
    request::{IntoRequest, ApiRequest}
};

#[derive(serde::Deserialize)]
struct UserBasic {
    id: UserId,
    name: String,
    level: i32
}

struct UserBasicRequest(UserId);

impl IntoRequest for UserBasicRequest {
    type Discriminant = UserId;
    type Response = UserBasic;
    fn into_request(self) -> (Self::Discriminant, ApiRequest) {
        let request = ApiRequest {
            path: format!("/user/{}/basic", self.0),
            parameters: Vec::default(),
        };

        (self.0, request)
    }
}

let client = ReqwestClient::new("XXXXXXXXXXXXX");
let basic = client.fetch(UserBasicRequest(UserId(1))).await.unwrap();
```

### Implementing your own API executor
If you don't wish to use reqwest, or want to use custom logic for which API key to use, you have to implement the [`Executor`](https://docs.rs/torn-api/latest/torn_api/executor/trait.Executor.html) trait for your custom executor.

## Safety
The crate is compiled with `#![forbid(unsafe_code)]`.

## Warnings
- ⚠️ The Torn v2 API, on which this wrapper is based, is under active development and changes frequently. No guarantees are made that this wrapper always matches the latest version of the API.
- ⚠️ This crate contains a lot of macro-heavy, auto-generated code. If you experience slow compile times, you may want try testing the [nightly only `-Zhint-mostly-unused` option](https://blog.rust-lang.org/inside-rust/2025/07/15/call-for-testing-hint-mostly-unused) to see if improvements in compile time apply to your use case.