cortexkit_provider_usage/
lib.rs

1//! Shared wire types for the `ai-provider-quota` module's `usage.get` payload.
2//!
3//! The quota module serves an array of [`ProviderUsage`] per request; ALF's
4//! router (`codexbar-window-extractors.ts`), astrocyte's capacity axis, and the
5//! `ck quota` renderer all consume that shape. This crate is the single
6//! definition those consumers compile against, so the wire shape cannot drift
7//! without a shared-crate PR every side reviews.
8//!
9//! # Shape, not policy
10//!
11//! These are pure data types. Read-time transform semantics are PRODUCER
12//! behavior documented on the relevant fields but NOT enforced here:
13//! - **Banked-reset relaxation:** the quota module may zero
14//!   [`RateWindow::used_percent`] (the EFFECTIVE number consumers pace on) and
15//!   carry the provider-reported truth in [`RateWindow::raw_used_percent`].
16//!   A consumer renders whatever the wire says; a sudden `0 → high` transition
17//!   is an honest disarm (credits spent / auth broke), not a glitch.
18//! - **Cache-only partial arrays:** the quota module never blocks on a fetch,
19//!   so a result may omit providers not yet swept. Missing ≠ zero.
20//! - **Degraded entries ride in-band:** a provider fetch failure is a normal
21//!   [`ProviderUsage`] carrying `error`, not a request-level failure.
22//!
23//! # Serialization contract consumers depend on
24//! - camelCase keys (`usedPercent`, `resetsAt`, `windowMinutes`,
25//!   `extraRateWindows`, `rawUsedPercent`, `accountInfo`, `savedResets`,
26//!   `usedCount`, `totalCount`).
27//! - A healthy entry MUST NOT carry `error` (consumers skip truthy-`error`
28//!   entries), so it is omitted when absent.
29//! - A window is emitted when it has a `usedPercent`; `resetsAt` is OPTIONAL and
30//!   omitted when the provider reports no reset (never fabricated).
31
32use serde::{Deserialize, Serialize};
33
34/// One rate-limit window: how much of a quota pool is spent and when it resets.
35#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
36#[serde(rename_all = "camelCase")]
37pub struct RateWindow {
38    /// 0..100 percent of the window's quota consumed. This is the EFFECTIVE
39    /// number consumers pace on: when banked-reset relaxation applies it is
40    /// zeroed, and the provider-reported percent moves to `raw_used_percent`.
41    pub used_percent: f64,
42    /// The provider-reported percent when `used_percent` has been relaxed to
43    /// an effective value (banked resets guarantee the window resets before
44    /// the wall). Present only on relaxed windows; human-facing UIs should
45    /// display this truth alongside the effective number.
46    #[serde(skip_serializing_if = "Option::is_none", default)]
47    pub raw_used_percent: Option<f64>,
48    /// ISO 8601 / RFC 3339 timestamp when the window resets. Omitted when the
49    /// provider reports no reset (e.g. an idle session window with nothing
50    /// pending) — never fabricated.
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub resets_at: Option<String>,
53    /// Window length in minutes. Omitted when the provider does not report one;
54    /// the consumer then paces on utilization alone rather than a burn rate.
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub window_minutes: Option<i64>,
57    /// Absolute consumed count in the window (e.g. tokens, requests). Present
58    /// only when the provider reports or derives it; human-facing UIs can show
59    /// "10,336 / 40,000" alongside the percentage for richer context.
60    #[serde(skip_serializing_if = "Option::is_none", default)]
61    pub used_count: Option<f64>,
62    /// Absolute total cap for the window. Present alongside `used_count` when
63    /// the provider knows the ceiling; omitted otherwise.
64    #[serde(skip_serializing_if = "Option::is_none", default)]
65    pub total_count: Option<f64>,
66}
67
68/// A per-model window bundled under one account (e.g. Antigravity's Geminis).
69#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
70#[serde(rename_all = "camelCase")]
71pub struct ExtraWindow {
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub title: Option<String>,
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub id: Option<String>,
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub window: Option<RateWindow>,
78}
79
80/// The window topology for one account: up to three account-wide pools plus an
81/// optional list of per-model pools.
82#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
83#[serde(rename_all = "camelCase")]
84pub struct Usage {
85    #[serde(skip_serializing_if = "Option::is_none")]
86    pub primary: Option<RateWindow>,
87    #[serde(skip_serializing_if = "Option::is_none")]
88    pub secondary: Option<RateWindow>,
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub tertiary: Option<RateWindow>,
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub extra_rate_windows: Option<Vec<ExtraWindow>>,
93}
94
95/// Account labels and subscription information supplied by a provider or vault.
96#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default)]
97#[serde(rename_all = "camelCase")]
98pub struct AccountInfo {
99    #[serde(skip_serializing_if = "Option::is_none", default)]
100    pub email: Option<String>,
101    #[serde(skip_serializing_if = "Option::is_none", default)]
102    pub org_name: Option<String>,
103    #[serde(skip_serializing_if = "Option::is_none", default)]
104    pub plan_type: Option<String>,
105}
106
107impl AccountInfo {
108    pub fn is_empty(&self) -> bool {
109        self.email.is_none() && self.org_name.is_none() && self.plan_type.is_none()
110    }
111}
112
113/// One saved reset credit and its expiry time.
114#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
115#[serde(rename_all = "camelCase")]
116pub struct CreditExpiry {
117    pub expires_at: String,
118}
119
120/// Saved reset credits reported by Codex's read-only credits endpoint.
121#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default)]
122#[serde(rename_all = "camelCase")]
123pub struct SavedResets {
124    #[serde(default)]
125    pub available_count: u32,
126    #[serde(skip_serializing_if = "Option::is_none", default)]
127    pub soonest_expires_at: Option<String>,
128    #[serde(default)]
129    pub credits: Vec<CreditExpiry>,
130}
131
132fn account_info_is_empty(value: &Option<AccountInfo>) -> bool {
133    value.as_ref().map(AccountInfo::is_empty).unwrap_or(true)
134}
135
136/// One provider/account's usage entry. The `/usage` response is an array of
137/// these. A fetch failure becomes an entry carrying `error` (silent-degrade),
138/// never a failure of the whole array.
139#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
140#[serde(rename_all = "camelCase")]
141pub struct ProviderUsage {
142    /// CodexBar provider name (e.g. "codex"), which consumers map to their own id.
143    pub provider: String,
144    /// Canonical API provider identifier — the models.dev slug for the same
145    /// provider (e.g. "openai" when `provider == "codex"`, "anthropic" for
146    /// "claude", "google" for "gemini", "xai" for "grok"). Present when the
147    /// producer knows the canonical name; absent for providers with no models.dev
148    /// counterpart, where consumers fall back to `provider`. Lets every consumer
149    /// key on one canonical name instead of each maintaining its own
150    /// CodexBar-name → canonical map.
151    #[serde(skip_serializing_if = "Option::is_none", default)]
152    pub api_provider: Option<String>,
153    #[serde(skip_serializing_if = "Option::is_none")]
154    pub account: Option<String>,
155    /// Which retrieval path produced this (e.g. "oauth") — observability only.
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub source: Option<String>,
158    #[serde(skip_serializing_if = "account_info_is_empty", default)]
159    pub account_info: Option<AccountInfo>,
160    #[serde(skip_serializing_if = "Option::is_none", default)]
161    pub fetched_at: Option<String>,
162    #[serde(skip_serializing_if = "Option::is_none", default)]
163    pub saved_resets: Option<SavedResets>,
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub usage: Option<Usage>,
166    /// Present only on a degraded entry. The consumer skips any entry with a
167    /// truthy `error`.
168    #[serde(skip_serializing_if = "Option::is_none")]
169    pub error: Option<String>,
170}
171
172impl ProviderUsage {
173    /// A healthy entry with resolved windows.
174    pub fn healthy(provider: &str, account: Option<String>, source: &str, usage: Usage) -> Self {
175        Self {
176            provider: provider.to_string(),
177            api_provider: None,
178            account,
179            source: Some(source.to_string()),
180            account_info: None,
181            fetched_at: None,
182            saved_resets: None,
183            usage: Some(usage),
184            error: None,
185        }
186    }
187
188    /// A degraded entry: the provider is named so the consumer can correlate,
189    /// but it carries only an error string and no windows.
190    pub fn degraded(provider: &str, error: impl std::fmt::Display) -> Self {
191        Self {
192            provider: provider.to_string(),
193            api_provider: None,
194            account: None,
195            source: None,
196            account_info: None,
197            fetched_at: None,
198            saved_resets: None,
199            usage: None,
200            error: Some(error.to_string()),
201        }
202    }
203}
204
205#[cfg(test)]
206mod tests {
207    use super::*;
208
209    #[test]
210    fn account_info_is_omitted_when_empty_and_keeps_partial_labels() {
211        let bare = ProviderUsage::healthy(
212            "codex",
213            None,
214            "oauth",
215            Usage {
216                primary: Some(RateWindow {
217                    used_percent: 10.0,
218                    raw_used_percent: None,
219                    resets_at: None,
220                    window_minutes: Some(300),
221                    used_count: None,
222                    total_count: None,
223                }),
224                ..Default::default()
225            },
226        );
227        let json = serde_json::to_string(&bare).unwrap();
228        assert!(
229            !json.contains("accountInfo"),
230            "empty accountInfo must be omitted"
231        );
232
233        let mut labeled = bare.clone();
234        labeled.account_info = Some(AccountInfo {
235            email: Some("a@b.com".to_string()),
236            org_name: None,
237            plan_type: Some("pro".to_string()),
238        });
239        let json = serde_json::to_string(&labeled).unwrap();
240        assert!(json.contains("\"email\":\"a@b.com\""));
241        assert!(json.contains("\"planType\":\"pro\""));
242        assert!(!json.contains("orgName"), "absent orgName must be omitted");
243    }
244
245    #[test]
246    fn saved_resets_use_camel_case_and_round_trip() {
247        let entry = ProviderUsage {
248            saved_resets: Some(SavedResets {
249                available_count: 2,
250                soonest_expires_at: Some("2026-07-31T20:11:35Z".to_string()),
251                credits: vec![CreditExpiry {
252                    expires_at: "2026-07-31T20:11:35Z".to_string(),
253                }],
254            }),
255            ..ProviderUsage::degraded("codex", "x")
256        };
257        let json = serde_json::to_string(&entry).unwrap();
258        assert!(json.contains("\"savedResets\""));
259        assert!(json.contains("\"availableCount\":2"));
260        assert!(json.contains("\"soonestExpiresAt\""));
261        let back: ProviderUsage = serde_json::from_str(&json).unwrap();
262        assert_eq!(back, entry);
263    }
264
265    #[test]
266    fn raw_used_percent_is_absent_from_unrelaxed_windows_and_camel_case_when_present() {
267        let unrelaxed = RateWindow {
268            used_percent: 41.0,
269            raw_used_percent: None,
270            resets_at: Some("2026-07-20T00:00:00Z".to_string()),
271            window_minutes: Some(10080),
272            used_count: None,
273            total_count: None,
274        };
275        let json = serde_json::to_string(&unrelaxed).unwrap();
276        assert!(
277            !json.contains("rawUsedPercent"),
278            "unrelaxed window must not carry the field"
279        );
280
281        let relaxed = RateWindow {
282            used_percent: 0.0,
283            raw_used_percent: Some(70.0),
284            resets_at: Some("2026-07-20T00:00:00Z".to_string()),
285            window_minutes: Some(10080),
286            used_count: None,
287            total_count: None,
288        };
289        let json = serde_json::to_string(&relaxed).unwrap();
290        assert!(json.contains("\"rawUsedPercent\":70.0"));
291        let back: RateWindow = serde_json::from_str(&json).unwrap();
292        assert_eq!(back, relaxed);
293    }
294
295    #[test]
296    fn healthy_entry_omits_error_and_degraded_entry_omits_usage() {
297        let healthy = ProviderUsage::healthy("codex", None, "oauth", Usage::default());
298        let json = serde_json::to_string(&healthy).unwrap();
299        assert!(!json.contains("error"));
300
301        let degraded = ProviderUsage::degraded("codex", "no session");
302        let json = serde_json::to_string(&degraded).unwrap();
303        assert!(json.contains("\"error\":\"no session\""));
304        assert!(!json.contains("usage"));
305    }
306
307    #[test]
308    fn api_provider_is_camel_case_present_when_set_and_omitted_when_absent() {
309        let mut entry = ProviderUsage::healthy("codex", None, "oauth", Usage::default());
310        let json = serde_json::to_string(&entry).unwrap();
311        assert!(
312            !json.contains("apiProvider"),
313            "absent api_provider must be omitted"
314        );
315
316        entry.api_provider = Some("openai".to_string());
317        let json = serde_json::to_string(&entry).unwrap();
318        assert!(json.contains("\"apiProvider\":\"openai\""));
319        let back: ProviderUsage = serde_json::from_str(&json).unwrap();
320        assert_eq!(back, entry);
321    }
322
323    #[test]
324    fn used_count_and_total_count_are_camel_case_and_omitted_when_absent() {
325        let window = RateWindow {
326            used_percent: 25.8,
327            raw_used_percent: None,
328            resets_at: Some("2026-07-26T14:09:00Z".to_string()),
329            window_minutes: Some(10080),
330            used_count: None,
331            total_count: None,
332        };
333        let json = serde_json::to_string(&window).unwrap();
334        assert!(
335            !json.contains("usedCount"),
336            "absent used_count must be omitted"
337        );
338        assert!(
339            !json.contains("totalCount"),
340            "absent total_count must be omitted"
341        );
342
343        let enriched = RateWindow {
344            used_count: Some(10336.0),
345            total_count: Some(40000.0),
346            ..window
347        };
348        let json = serde_json::to_string(&enriched).unwrap();
349        assert!(json.contains("\"usedCount\":10336.0"));
350        assert!(json.contains("\"totalCount\":40000.0"));
351        let back: RateWindow = serde_json::from_str(&json).unwrap();
352        assert_eq!(back, enriched);
353    }
354}
cortexkit_provider_usage/lib.rs

cortexkit_provider_usage/
lib.rs
