# randomorg-rpc

Async Rust client for the [RANDOM.ORG JSON-RPC API (Release 4)][api].

True random numbers from atmospheric noise — basic generation, signed
generation, tickets, and verification — all wired up against the live API.

## Why

The existing [`randomorg`](https://crates.io/crates/randomorg) crate is stuck
on Release 1 (last published 2021), only covers the basic `generate*`
methods, and has no support for the Signed API, tickets, or verification.

This crate covers the full Release 4 surface that the [official Python client][py]
exposes.

## Install

```toml
[dependencies]
randomorg-rpc = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Quick start

```rust,no_run
use randomorg_rpc::{Client, IntegersParams};

#[tokio::main]
async fn main() -> Result<(), randomorg_rpc::Error> {
    let client = Client::new(std::env::var("RANDOM_ORG_API_KEY").unwrap());

    let r = client
        .generate_integers(IntegersParams::new(5, 1, 100))
        .await?;
    println!("{:?}", r.random.data);
    Ok(())
}
```

## Signed generation + verification

```rust,no_run
use randomorg_rpc::{Client, IntegersParams, SignedExtras};
use serde_json::json;

# async fn run(client: Client) -> Result<(), randomorg_rpc::Error> {
let r = client
    .generate_signed_integers(
        IntegersParams::new(3, 1, 6),
        SignedExtras::new().user_data(json!({"label": "dice-roll"})),
    )
    .await?;

let nums: Vec<i64> = r.data().unwrap();
let serial = r.serial_number().unwrap();

// Server-side verify (random.org does not publish their RSA pubkey,
// so offline verification is not possible).
let v = client.verify_signature(&r.random.0, &r.signature).await?;
assert!(v.authenticity);

// Re-fetch by serial number later.
let _again = client.get_result(serial).await?;
# Ok(()) }
```

## Coverage

| Method | |
|---|---|
| `generateIntegers` / `generateSignedIntegers` | ✅ |
| `generateIntegerSequences` (uniform + multiform), signed too | ✅ |
| `generateDecimalFractions` / signed | ✅ |
| `generateGaussians` / signed | ✅ |
| `generateStrings` / signed | ✅ |
| `generateUUIDs` / signed | ✅ |
| `generateBlobs` / signed | ✅ |
| `getResult` | ✅ |
| `verifySignature` (server-side) | ✅ |
| `createTickets` / `revealTickets` / `listTickets` / `getTicket` | ✅ |
| `getUsage` | ✅ |
| `createUrl` / `createHtml` (client-side helpers) | ✅ |

## Notes

- **Verification is server-side only.** random.org doesn't publish their RSA
  public key, so there's no offline verification path. `Client::verify_signature`
  relays to their `verifySignature` endpoint.
- Set `RANDOM_ORG_API_KEY` to run the integration test suite:
  `cargo test -- --test-threads=1`.

## License

0BSD — see [LICENSE](LICENSE).

[api]: https://api.random.org/json-rpc/4
[py]: https://github.com/RandomOrg/JSON-RPC-Python
