Skip to main content

zai_rs/
usage.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 five-hour time window
7//! (`TIME_LIMIT`) and a weekly token 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::client::ZaiClient;
19//! use zai_rs::usage::CodingPlanUsageRequest;
20//!
21//! # async fn go(client: ZaiClient) -> zai_rs::ZaiResult<()> {
22//! let resp = CodingPlanUsageRequest::new().send_via(&client).await?;
23//!
24//! let usage = resp.summary();
25//!
26//! if let Some(five_hour) = usage.time_limit() {
27//!     tracing::info!(
28//!         "5h window: {}/{} used ({} remaining, {}%), resets at {}",
29//!         five_hour.used,
30//!         five_hour.quota,
31//!         five_hour.remaining,
32//!         five_hour.percentage,
33//!         five_hour
34//!             .next_reset_at
35//!             .as_ref()
36//!             .map_or_else(|| "?".to_string(), |datetime| datetime.to_rfc3339())
37//!     );
38//! }
39//! if let Some(weekly) = usage.tokens_limit() {
40//!     tracing::info!(
41//!         "weekly tokens: {} remaining of {}",
42//!         weekly.remaining,
43//!         weekly.quota
44//!     );
45//! }
46//! # Ok(())
47//! # }
48//! ```
49//!
50//! ## Switching to the international endpoint
51//!
52//! Override the monitor family base on the [`ZaiClient`] builder:
53//!
54//! ```rust,no_run
55//! use zai_rs::client::{ApiFamily, ZaiClient};
56//! use zai_rs::usage::CodingPlanUsageRequest;
57//!
58//! # async fn go() -> zai_rs::ZaiResult<()> {
59//! static INTL: &str = "https://api.z.ai/api/monitor";
60//! let client = ZaiClient::builder("your-api-key")
61//!     .endpoint(ApiFamily::Monitor, INTL)
62//!     .build()?;
63//! let resp = CodingPlanUsageRequest::new().send_via(&client).await?;
64//! # Ok(())
65//! # }
66//! ```
67
68mod data;
69
70pub use data::{
71    CodingPlanQuotaKind, CodingPlanQuotaLimit, CodingPlanQuotaSummary, CodingPlanUsageData,
72    CodingPlanUsageDetail, CodingPlanUsageRequest, CodingPlanUsageResponse, CodingPlanUsageSummary,
73};
74
75use crate::{ZaiResult, client::ZaiClient};
76
77/// Query the Coding Plan usage endpoint via `client` and return the typed raw
78/// response.
79pub async fn query(client: &ZaiClient) -> ZaiResult<CodingPlanUsageResponse> {
80    CodingPlanUsageRequest::new().send_via(client).await
81}
82
83/// Query the Coding Plan usage endpoint via `client` and return a normalized
84/// summary.
85pub async fn query_summary(client: &ZaiClient) -> ZaiResult<CodingPlanUsageSummary> {
86    query(client).await.map(|response| response.summary())
87}