> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotastellar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK

> Official Rust SDK for the RotaStellar API

# Rust SDK

The official Rust SDK for RotaStellar, providing type-safe primitives for orbital compute and space intelligence applications.

<Info>
  **Status:** Early Access — [Request API key](https://rotastellar.com/developers)
</Info>

<Warning>
  The Rust SDK currently provides **types only**. The HTTP client is coming in a future release. For full API access, use the [Python SDK](/sdks/python) or [Node.js SDK](/sdks/node).
</Warning>

## Installation

Add to your `Cargo.toml`:

```toml theme={null}
[dependencies]
rotastellar = "0.1"
```

Or use cargo:

```bash theme={null}
cargo add rotastellar
```

## Quick Start

```rust theme={null}
use rotastellar::types::{Position, Orbit, Satellite};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a position (e.g., Kennedy Space Center)
    let pos = Position::new(28.5729, -80.6490, 0.0)?;
    println!("Position: {}, {}", pos.latitude, pos.longitude);

    // Create an ISS-like orbit
    let orbit = Orbit::new(6778.0, 0.0001, 51.6, 100.0, 90.0, 0.0)?;
    println!("Orbital period: {:.1} minutes", orbit.orbital_period_minutes());
    println!("Apogee: {:.1} km, Perigee: {:.1} km", orbit.apogee_km(), orbit.perigee_km());

    Ok(())
}
```

## Available Types

### Position

Geographic position with altitude:

```rust theme={null}
use rotastellar::types::Position;

// Create with validation
let pos = Position::new(28.5729, -80.6490, 408.0)?;

// Access fields
println!("Latitude: {}", pos.latitude);
println!("Longitude: {}", pos.longitude);
println!("Altitude: {} km", pos.altitude_km);
```

| Field         | Type  | Description                        |
| ------------- | ----- | ---------------------------------- |
| `latitude`    | `f64` | Latitude in degrees (-90 to 90)    |
| `longitude`   | `f64` | Longitude in degrees (-180 to 180) |
| `altitude_km` | `f64` | Altitude above sea level in km     |

### Orbit

Keplerian orbital elements:

```rust theme={null}
use rotastellar::types::Orbit;

// Create an orbit (ISS-like)
let orbit = Orbit::new(
    6778.0,   // semi_major_axis_km
    0.0001,   // eccentricity
    51.6,     // inclination_deg
    100.0,    // raan_deg
    90.0,     // arg_periapsis_deg
    0.0       // true_anomaly_deg
)?;

// Computed properties
println!("Period: {:.1} minutes", orbit.orbital_period_minutes());
println!("Apogee: {:.1} km", orbit.apogee_km());
println!("Perigee: {:.1} km", orbit.perigee_km());
println!("Mean motion: {:.2} rev/day", orbit.mean_motion());
```

| Field                | Type  | Description                       |
| -------------------- | ----- | --------------------------------- |
| `semi_major_axis_km` | `f64` | Semi-major axis in km             |
| `eccentricity`       | `f64` | Orbital eccentricity (0-1)        |
| `inclination_deg`    | `f64` | Inclination in degrees (0-180)    |
| `raan_deg`           | `f64` | Right ascension of ascending node |
| `arg_periapsis_deg`  | `f64` | Argument of periapsis             |
| `true_anomaly_deg`   | `f64` | True anomaly                      |

### Satellite

Satellite information with optional orbit and position:

```rust theme={null}
use rotastellar::types::{Satellite, Position, Orbit};

let sat = Satellite::new("sat_123", 25544, "ISS")
    .with_operator("NASA/Roscosmos")
    .with_constellation("Space Station")
    .with_position(Position::new(28.5729, -80.6490, 408.0)?)
    .with_orbit(orbit);

println!("Name: {}", sat.name);
println!("NORAD ID: {}", sat.norad_id);
if let Some(pos) = &sat.position {
    println!("At: {}, {}", pos.latitude, pos.longitude);
}
```

### TimeRange

Time range for queries:

```rust theme={null}
use rotastellar::types::TimeRange;

// Create a 24-hour time range starting now
let range = TimeRange::next_hours(24.0);
println!("Start: {}", range.start);
println!("End: {}", range.end);
```

## Configuration

The SDK provides configuration utilities for when the HTTP client is available:

```rust theme={null}
use rotastellar::{Config, ConfigBuilder};

let config = Config::default();
println!("Base URL: {}", config.base_url);
println!("Timeout: {:?}", config.timeout);
```

## Authentication Utilities

Validate and mask API keys:

```rust theme={null}
use rotastellar::{validate_api_key, mask_api_key, Environment};

// Validate an API key
match validate_api_key(Some("rs_live_abc123")) {
    Ok(env) => println!("Valid key for {:?} environment", env),
    Err(e) => println!("Invalid: {}", e),
}

// Mask a key for logging
let masked = mask_api_key("rs_live_abc123def456");
println!("Masked: {}", masked);  // rs_live_abc...
```

## Error Handling

```rust theme={null}
use rotastellar::error::{RotaStellarError, ValidationError};
use rotastellar::types::Position;

fn create_position() -> Result<Position, RotaStellarError> {
    // This will fail validation (latitude > 90)
    let pos = Position::new(91.0, 0.0, 0.0)?;
    Ok(pos)
}

match create_position() {
    Ok(pos) => println!("Created: {:?}", pos),
    Err(RotaStellarError::Validation(e)) => {
        println!("Validation error on '{}': {}", e.field, e.message);
    }
    Err(e) => println!("Error: {}", e),
}
```

### Error Types

| Error                              | Description                 |
| ---------------------------------- | --------------------------- |
| `RotaStellarError::Validation`     | Input validation failed     |
| `RotaStellarError::Authentication` | API key issues              |
| `RotaStellarError::Api`            | API returned an error       |
| `RotaStellarError::Network`        | Network connectivity issues |

## Constants

```rust theme={null}
use rotastellar::{EARTH_RADIUS_KM, EARTH_MU};

println!("Earth radius: {} km", EARTH_RADIUS_KM);  // 6378.137
println!("Earth GM: {} km³/s²", EARTH_MU);         // 398600.4418
```

## Serde Support

All types implement `Serialize` and `Deserialize`:

```rust theme={null}
use rotastellar::types::Position;
use serde_json;

let pos = Position::new(28.5729, -80.6490, 408.0)?;

// Serialize
let json = serde_json::to_string(&pos)?;
println!("{}", json);

// Deserialize
let parsed: Position = serde_json::from_str(&json)?;
```

## Coming Soon

The following features are planned for future releases:

* **HTTP Client** — Full API client with async support
* **Blocking Client** — Synchronous API for non-async contexts
* **Streaming** — Real-time satellite position updates
* **TLE Parsing** — Two-line element set parsing and propagation

## Source Code

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/rotastellar/rotastellar-rust">
    View source, report issues, and contribute.
  </Card>

  <Card title="crates.io" icon="rust" href="https://crates.io/crates/rotastellar">
    Package page and version history.
  </Card>
</CardGroup>