# kittycad

The official Rust client for the [Zoo API](https://zoo.dev/docs/api) — CAD
file conversion and analysis, text-to-CAD, the Zoo modeling engine, and
account management, from Rust.

[![docs.rs](https://docs.rs/kittycad/badge.svg)](https://docs.rs/kittycad)
[![crates.io](https://img.shields.io/crates/v/kittycad.svg)](https://crates.io/crates/kittycad)

The client is generated from Zoo's [OpenAPI spec](https://api.zoo.dev), so it
tracks the live API surface. It is async (Tokio), returns strongly-typed
results, and retries transient failures automatically.

## Installation

```toml
[dependencies]
kittycad = "0.5.7"
tokio = { version = "1", features = ["rt", "macros"] }
```

## Authentication

Generate an API token in your [Zoo account settings](https://zoo.dev/account),
then either export it:

```bash
export ZOO_API_TOKEN="your-token"   # KITTYCAD_API_TOKEN also works
```

```rust,no_run
let client = kittycad::Client::new_from_env();
```

or pass it explicitly:

```rust,no_run
let client = kittycad::Client::new("your-token");
```

## First call

Convert a CAD file from one format to another:

```rust,no_run
use kittycad::types::{FileExportFormat, FileImportFormat};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = kittycad::Client::new_from_env();
    let input = std::fs::read("part.step")?;

    let conversion = client
        .file()
        .create_conversion(
            FileExportFormat::Stl,
            FileImportFormat::Step,
            &bytes::Bytes::from(input),
        )
        .await?;

    println!("status: {:?}", conversion.status);
    Ok(())
}
```

See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough and
[EXAMPLES.md](EXAMPLES.md) for more worked examples.

## What's in the box

Each area of the API is reached through a method on `Client`:

| Accessor | What it does |
|---|---|
| `client.file()` | CAD file conversion, volume, mass, density, surface area, center of mass |
| `client.ml()` | Text-to-CAD, KCL code completions, proprietary-format-to-KCL conversion |
| `client.modeling()` | WebSocket connection to the Zoo modeling engine |
| `client.executor()` | Remote code execution environments |
| `client.unit()` | Unit conversions (length, mass, pressure, torque, …) |
| `client.users()` / `client.orgs()` | Account, org and member management |
| `client.api_tokens()` / `client.service_accounts()` | Credential management |
| `client.api_calls()` | Query your API usage (debugging, billing) |
| `client.payments()` | Billing and payment information |
| `client.oauth2()` | OAuth 2.0 grant flows |

Full per-method reference: [docs.rs/kittycad](https://docs.rs/kittycad).

## Errors, retries, pagination

- Every method returns `Result<T, kittycad::types::error::Error>`; server
  failures carry the HTTP status and response body.
- Transient failures are retried with backoff via `reqwest-retry`.
- List endpoints have a `*_stream` variant that paginates for you as a
  `futures::Stream`.

## Contributing

The code in this repository is **generated** from
[spec.json](https://github.com/KittyCAD/kittycad.rs/blob/main/spec.json) —
please don't edit it by hand (a bot closes such PRs). To regenerate locally,
run `make generate`. Maintainer docs (releasing, CI smoke tests) live in
[MAINTAINERS.md](#) *(moved out of this README; see note in sample)*.

## Support

- API questions: [zoo.dev/docs](https://zoo.dev/docs) or api@zoo.dev
- Bugs in this client: [open an issue](https://github.com/KittyCAD/kittycad.rs/issues)

## License

MIT