# rust-umami
An ergonomic async Rust client for Umami's public analytics ingestion API.
This crate is deliberately small: it sends pageviews, custom events, identify/session properties, performance metrics, and batches. It does not log in, manage bearer tokens or API keys, or expose Umami's reporting/admin API.
## Usage
```toml
[dependencies]
rust-umami = "0.1"
serde_json = "1"
```
```rust
use rust_umami::{Client, Result};
use serde_json::json;
async fn track() -> Result<()> {
let umami = Client::new(
"https://analytics.example.com",
"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
)?;
umami.pageview("/docs").title("Documentation").send().await?;
umami
.event("signup")
.url("/pricing")
.data(json!({ "plan": "pro", "revenue": 49.0, "currency": "USD" }))
.send()
.await?;
Ok(())
}
```
`Client::new` accepts an instance root, an `/api` URL, or the exact `/api/send` endpoint. Use `Client::cloud(website_id)` for Umami Cloud's collection gateway.
## Server-side tracking
When a Rust server sends an event, Umami otherwise sees the server's IP and user-agent. Forward the original visitor context when it matters for attribution and session detection:
```rust
use rust_umami::{Client, Context, Result};
use std::net::{IpAddr, Ipv4Addr};
async fn track_request() -> Result<()> {
let context = Context::new()
.hostname("example.com")
.language("en-US")
.ip(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 10)))
.user_agent("Mozilla/5.0 ...");
let umami = Client::builder(
"https://analytics.example.com",
"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
)
.default_context(context)
.build()?;
umami.event("payment-received").url("/checkout").send().await?;
Ok(())
}
```
The client always sends a valid HTTP `User-Agent` (`rust-umami/<version>` by default), as required by Umami. The visitor user-agent above is a separate value inside the analytics payload.
## Visitor sessions
A `Client` is stateless and can be shared across visitors. For several calls from one visitor, `Session` automatically carries Umami's cache value forward:
```rust
use rust_umami::{Client, Result};
use serde_json::json;
async fn track_visitor(umami: &Client) -> Result<()> {
let visitor = umami.session().distinct_id("user-123");
visitor.pageview("/").send().await?;
visitor
.identify("user-123")
.data(json!({ "plan": "pro" }))
.send()
.await?;
visitor
.event("download")
.data(json!({ "format": "pdf" }))
.send()
.await?;
Ok(())
}
```
Create a separate session for each visitor. Cloning a session intentionally shares its cache state.
## Performance and batches
```rust
use rust_umami::{Client, Result};
use serde_json::json;
async fn send_metrics(umami: &Client) -> Result<()> {
umami
.performance("/pricing")
.lcp(1_250.0)
.inp(80.0)
.cls(0.03)
.fcp(620.0)
.ttfb(140.0)
.send()
.await?;
let result = umami
.batch()
.push(umami.pageview("/one"))
.push(umami.event("download").data(json!({ "format": "pdf" })))
.send()
.await?;
assert!(result.is_success());
Ok(())
}
```
Umami accepts at most 500 items per batch; the crate checks that limit locally. Partial batch failures are returned in `BatchResponse::details` rather than converted into an HTTP error.
## Error behavior
Non-2xx responses retain Umami's status, error code, message, and JSON body. `Error::is_retryable()` recognizes transport failures, rate limits, and server errors, but the crate never retries automatically because that could duplicate an event.
The API targets the current Umami v3 `/api/send` and `/api/batch` contract. Basic pageview/custom-event sending remains compatible with Umami v2 instances that expose `/api/send`.
## Publishing
Publishing is automated by [`.github/workflows/publish.yml`](.github/workflows/publish.yml) using crates.io trusted publishing, so the repository does not store a registry token.
Trusted publishing can only be configured after the crate exists. Publish the first version manually with `cargo publish --locked`, then add a GitHub trusted publisher in the crate's crates.io settings with these values:
- Repository owner: `egoist`
- Repository: `rust-umami`
- Workflow: `publish.yml`
- Environment: `crates-io`
For later versions, bump `Cargo.toml`, commit it, and push a matching `v<version>` tag:
```sh
git tag v0.2.0
git push origin v0.2.0
```
The workflow verifies the tag, runs formatting, tests, Clippy, docs, and a package dry run, publishes with a short-lived credential, then creates the GitHub Release with generated notes.