zai_rs/usage/
mod.rs

1//! # Coding Plan Usage / Quota Query
2//!
3//! Query the remaining quota and consumption statistics for the GLM Coding
4//! Plan via the monitor API `GET /api/monitor/usage/quota/limit`.
5//!
6//! The Coding Plan applies two quota windows — a per-5-hour time window
7//! (`TIME_LIMIT`) and a weekly tokens window (`TOKENS_LIMIT`) — and reports the
8//! configured cap, consumed percentage, and next reset time for each. This
9//! module surfaces them as strongly-typed [`CodingPlanUsageResponse`].
10//!
11//! Verified against the official `glm-plan-usage` plugin
12//! (<https://docs.bigmodel.cn/cn/coding-plan/extension/usage-query-plugin>)
13//! and the community CLI <https://github.com/JinHanAI/coding-plan-monitor>.
14//!
15//! ## Quick start
16//!
17//! ```rust,no_run
18//! use zai_rs::usage::CodingPlanUsageRequest;
19//!
20//! # async fn go(key: String) -> zai_rs::ZaiResult<()> {
21//! let resp = CodingPlanUsageRequest::new(key).send().await?;
22//!
23//! let usage = resp.summary();
24//!
25//! if let Some(five_hour) = usage.time_limit() {
26//!     tracing::info!(
27//!         "5h window: {}/{} used ({} remaining, {}%), resets at {}",
28//!         five_hour.used,
29//!         five_hour.quota,
30//!         five_hour.remaining,
31//!         five_hour.percentage,
32//!         five_hour
33//!             .next_reset_at
34//!             .as_ref()
35//!             .map_or_else(|| "?".to_string(), |datetime| datetime.to_rfc3339())
36//!     );
37//! }
38//! if let Some(weekly) = usage.tokens_limit() {
39//!     tracing::info!(
40//!         "weekly tokens: {} remaining of {}",
41//!         weekly.remaining,
42//!         weekly.quota
43//!     );
44//! }
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! ## Switching to the international endpoint
50//!
51//! ```rust,no_run
52//! use zai_rs::usage::CodingPlanUsageRequest;
53//!
54//! # async fn go(key: String) -> zai_rs::ZaiResult<()> {
55//! let resp = CodingPlanUsageRequest::new(key)
56//!     .with_monitor_base("https://api.z.ai/api/monitor")
57//!     .send()
58//!     .await?;
59//! # Ok(())
60//! # }
61//! ```
62
63pub mod data;
64
65pub use data::{
66    CodingPlanQuotaKind, CodingPlanQuotaLimit, CodingPlanQuotaSummary, CodingPlanUsageData,
67    CodingPlanUsageDetail, CodingPlanUsageRequest, CodingPlanUsageResponse, CodingPlanUsageSummary,
68};
69
70use crate::ZaiResult;
71
72/// Query the Coding Plan usage endpoint and return the typed raw response.
73pub async fn query(key: impl Into<String>) -> ZaiResult<CodingPlanUsageResponse> {
74    CodingPlanUsageRequest::new(key.into()).send().await
75}
76
77/// Query the Coding Plan usage endpoint and return a normalized summary.
78pub async fn query_summary(key: impl Into<String>) -> ZaiResult<CodingPlanUsageSummary> {
79    query(key).await.map(|response| response.summary())
80}
zai_rs/usage/mod.rs

zai_rs/usage/
mod.rs
