matomo/
lib.rs

1//! HTTP client-agnostic Rust bindings for the Matomo Reporting API, focused on
2//! data export and migration.
3//!
4//! The crate is split into a transport-agnostic core ([`Client`], [`Endpoint`],
5//! [`Query`]) and an optional [`reqwest`]-backed transport behind a feature
6//! flag. Bring your own HTTP client by implementing [`Client`].
7//!
8//! Matomo's API is a single dispatch endpoint: every call is a
9//! `POST {base}/index.php` with a `module=API&method=Module.action&format=json`
10//! form body. Errors arrive as HTTP 200 with a `{"result":"error",...}` JSON
11//! envelope rather than via status codes, so [`Endpoint::parse_response`]
12//! detects that envelope instead of mapping status codes.
13//!
14//! # Features
15//!
16//! - `reqwest` — enables [`crate::reqwest::MatomoClient`], a ready-made
17//!   [`Client`]. No TLS backend is selected by default; pair it with one below.
18//! - `reqwest-rustls` — `reqwest` with `rustls`.
19//! - `reqwest-native-tls` — `reqwest` with the OS-native TLS stack.
20//! - `chrono` / `time` — `From` conversions into [`Date`].
21//!
22//! All features are off by default. If none of the `reqwest-*` features fit,
23//! implement [`Client`] yourself against any HTTP backend.
24
25#![forbid(unsafe_code)]
26
27mod auth;
28mod de;
29pub mod endpoints;
30mod error;
31mod models;
32mod params;
33mod request;
34mod transport;
35
36pub use auth::Auth;
37pub use error::{ApiErrorKind, Error, Result};
38pub use models::{
39    ActionDetail, ActionPage, Download, GoalConversion, Outlink, ReferrerAll, ReferrerType, Visit,
40    VisitorType, VisitsSummary,
41};
42pub use params::{Date, DateRange, IdSite, Limit, Period, RangeEnd, Segment};
43pub use request::Params;
44pub use transport::{Client, Endpoint, ParseError, Query, QueryError};
45
46#[cfg(feature = "reqwest")]
47pub mod reqwest;
48
49/// Back-compat alias: the reqwest-backed concrete client also answers to
50/// `matomo::MatomoClient`, but the ergonomic entry point most code reaches for
51/// is here as `matomo::reqwest::MatomoClient`.
52#[cfg(feature = "reqwest")]
53pub use reqwest::{Cursor, MatomoClient, MatomoClientError, VisitStream};
54
55#[cfg(feature = "chrono")]
56impl From<chrono::NaiveDate> for Date {
57    fn from(d: chrono::NaiveDate) -> Self {
58        use chrono::Datelike;
59        Date::Ymd(d.year() as u16, d.month() as u8, d.day() as u8)
60    }
61}
62
63#[cfg(feature = "time")]
64impl From<time::Date> for Date {
65    fn from(d: time::Date) -> Self {
66        Date::Ymd(d.year() as u16, u8::from(d.month()), d.day())
67    }
68}
matomo/lib.rs

matomo/
lib.rs
