carbem 0.5.0

A Rust library for retrieving carbon emission values from cloud providers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

use serde::{Deserialize, Serialize};

// ============================================================================
// Generic structs
// ============================================================================

// IBM grouping options for carbon emissions
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum IbmGroupBy {
    #[default]
    Month,
    Location,
    Service,
    Account,
}

impl IbmGroupBy {
    pub fn as_str(&self) -> &'static str {
        match self {
            IbmGroupBy::Month => "month",
            IbmGroupBy::Location => "location",
            IbmGroupBy::Service => "service",
            IbmGroupBy::Account => "account",
        }
    }
}

// ============================================================================
// Provider Configuration Types
// ============================================================================

// Configuration for IBM Cloud provider (authentication)
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct IbmConfig {
    pub api_key: String,
}

// ============================================================================
// Query Configuration Types
// ============================================================================

// IBM query configuration for Carbon Calculator API
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IbmQueryConfig {
    // Mandatory enterprise ID for IBM Cloud
    pub enterprise_id: String,

    // Grouping option for results
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group_by: Option<IbmGroupBy>,

    // Enterprise account ID to filter (optional)
    // Only applicable for enterprise accounts, not standard accounts
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enterprise_account_id: Option<String>,

    // Pagination limit (optional, default is 10)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i32>,

    // Pagination offset (optional, default is 0)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<i32>,
}

impl Default for IbmQueryConfig {
    fn default() -> Self {
        Self {
            enterprise_id: String::new(),
            group_by: Some(IbmGroupBy::Month),
            enterprise_account_id: None,
            limit: None,
            offset: None,
        }
    }
}

impl IbmQueryConfig {
    // Validates that all required fields are present
    pub fn validate(&self) -> Result<(), String> {
        // Validate mandatory enterprise_id
        if self.enterprise_id.is_empty() {
            return Err("enterprise_id is required and cannot be empty".to_string());
        }

        Ok(())
    }
}

// ============================================================================
// API Request Types
// ============================================================================

// IBM Carbon Calculator API query parameters
#[derive(Debug, Clone, Serialize)]
pub struct IbmCarbonEmissionRequest {
    pub(super) enterprise_id: String,

    // Date filtering - examples: "gte:2023-01", "lte:2023-03"
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) month: Option<Vec<String>>,

    // Location filtering - examples: "Dallas", "Frankfurt", "Washington DC"
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) locations: Option<Vec<String>>,

    // Service filtering - examples: "Cloud Object Storage", "Kubernetes Service"
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) services: Option<Vec<String>>,

    // Enterprise account ID filter (optional, only for enterprise accounts)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) enterprise_account_id: Option<String>,

    // Grouping - examples: "month", "location", "service", "account"
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) group_by: Option<String>,

    // Pagination limit
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) limit: Option<i32>,

    // Pagination offset
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(super) offset: Option<i32>,
}

// ============================================================================
// API Response Types
// ============================================================================

// Month information in IBM response
#[allow(dead_code)] // min/max reserved for time range validation in future
#[derive(Debug, Clone, Deserialize)]
pub struct IbmMonthInfo {
    pub(super) value: String,
    #[serde(default)]
    pub(super) min: Option<String>,
    #[serde(default)]
    pub(super) max: Option<String>,
}

// Group by information in IBM response
#[derive(Debug, Clone, Deserialize)]
pub struct IbmGroupByInfo {
    #[serde(rename = "type")]
    pub(super) group_type: String,
    pub(super) value: String,
}

// IBM Carbon emission data point
#[derive(Debug, Clone, Deserialize)]
pub struct IbmEmissionData {
    // Account ID
    pub(super) account_id: String,

    // Carbon emissions in grams CO2e (note: API returns grams, we convert to kg)
    pub(super) carbon_emission: f64,

    // Energy consumption in Wh
    pub(super) energy_consumption: f64,

    // Month information
    pub(super) month: IbmMonthInfo,

    // Group by information
    #[serde(default)]
    pub(super) group_by: Option<IbmGroupByInfo>,

    // Location (when grouped by location)
    #[serde(default)]
    pub(super) location: Option<String>,

    // Service (when grouped by service)
    #[serde(default)]
    pub(super) service: Option<String>,
}

// Pagination link
#[allow(dead_code)] // href reserved for pagination navigation in future
#[derive(Debug, Clone, Deserialize)]
pub struct IbmPaginationLink {
    pub(super) href: String,
}

// IBM Carbon Calculator API response structure
#[allow(dead_code)] // Pagination fields reserved for future use
#[derive(Debug, Clone, Deserialize)]
pub struct IbmCarbonEmissionResponse {
    pub(super) carbon_emissions: Vec<IbmEmissionData>,

    // Total emissions across all results
    #[serde(default)]
    pub(super) total_emission: Option<f64>,

    // Pagination info
    #[serde(default)]
    pub(super) offset: Option<i32>,

    #[serde(default)]
    pub(super) limit: Option<i32>,

    #[serde(default)]
    pub(super) total_count: Option<i64>,

    // Pagination links
    #[serde(default)]
    pub(super) first: Option<IbmPaginationLink>,

    #[serde(default)]
    pub(super) last: Option<IbmPaginationLink>,

    #[serde(default)]
    pub(super) previous: Option<IbmPaginationLink>,

    #[serde(default)]
    pub(super) next: Option<IbmPaginationLink>,
}