rust-umami 0.1.1

An ergonomic Rust client for Umami Analytics event ingestion
Documentation
# 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.