carbonfr-sdk 0.2.0

Async Rust client for the carbon-fr API — real-time and historical carbon intensity of French electricity.
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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
//! DTO de réponse (et un DTO de requête, [`CreateWebhookRequest`]) du contrat
//! `/v1`, dupliqués depuis les schémas `components.schemas` de
//! `crates/adapter-http/tests/openapi.snapshot.json` (ADR-0031 décision 5) —
//! aucune dépendance à `carbonfr-core`/`carbonfr-adapter-http`.
//!
//! **Champs publics, aucun `#[non_exhaustive]`** (ADR-0030 §3 : « Les structs
//! à champs publics n'en reçoivent jamais [`#[non_exhaustive]`] […], y
//! compris pour le futur SDK Rust » — cette clause visait explicitement ces
//! types) : ce sont des types de données, pas des invariants à protéger par
//! construction, et doivent rester constructibles par littéral côté
//! appelant (tests, code applicatif). Conséquence assumée : ajouter un champ
//! public à l'une d'elles sera un bump *minor*, jamais un
//! `#[non_exhaustive]` posé après coup (casserait justement la construction
//! par littéral que cette doctrine protège).
//!
//! **Horodatages** : `time::OffsetDateTime` (RFC 3339, `time::serde::rfc3339`
//! / `rfc3339::option`) pour tout champ réellement RFC 3339 (`timestamp`,
//! `from`/`to`, `start`/`end`, `valid_at`/`run_at`, `at`, `disabled_at`).
//! **Restent `String`, délibérément** (pas des instants RFC 3339) :
//! `vintage` (`HistoryPoint`/`IntensityResponse` : étiquette de révision, ex.
//! `définitif` — distinct de `CostReferenceEntry::vintage`, un millésime
//! entier), `PriceResponse::vintage` (millésime réglementaire, ex. `2026-H2`,
//! pas une date), `RulesetInfo::hourly_switchover` (date **sans** heure, ex.
//! `2030-01-01`, confirmé par `tests/fixtures/eligibility_rulesets.json` —
//! `time::serde::rfc3339` échouerait dessus) et `VisitStatsResponse::since`
//! (`ISO YYYY-MM-DD`, même raison).
//!
//! **Champs `String` plutôt qu'un enum dupliqué** pour tout catalogue
//! **non** listé par `enums_to_duplicate` dans `sdk-spec.json` (`filiere`,
//! `technology`/`source`/`perimeter`/`basis` du LCOE, `pillar`/`basis` d'un
//! signal d'éligibilité…) : ADR-0030 §3 classe ces catalogues internes à
//! `core` comme `#[non_exhaustive]` (voués à grandir), mais la mission I6 ne
//! les a pas mis dans le périmètre des enums à dupliquer — les garder en
//! `String` évite d'inventer côté SDK une liste fermée que le serveur ne
//! promet pas.
//!
//! **Entiers** : `format: int32` → `u32`, `format: int64` → `u64` (compteurs
//! sur un historique long : `StatsBucket`/`StatsResponse::count`,
//! `VisitStatsResponse::total`/`unique`), pas de `format` déclaré → `u32`
//! (bornés en pratique : nombre d'entrées d'un catalogue, de créneaux…).
//! `MethodologyInfo::id` reste délibérément `String` (pas [`Methodology`]) :
//! c'est un catalogue de **découverte**, qui peut lister une méthode
//! `planned` non encore sélectionnable — le typer figerait la désérialisation
//! le jour où une 3ᵉ méthode y apparaît avant que `Methodology` ne la
//! connaisse.

use serde::{Deserialize, Serialize};
use time::OffsetDateTime;

use crate::enums::{
    EligibilityFramework, EligibilitySignalProvenance, EligibilitySignalVerdict, Estimator,
    FlowDirection, Interval, Methodology, ThresholdDirection, WebhookStatus,
};
use crate::region::Region;

// --- Intensité (`/v1/intensity/*`) -----------------------------------------

/// Valeur d'intensité carbone (`IntensityResponse::intensity`).
#[derive(Debug, Clone, PartialEq, Deserialize)]
pub struct IntensityValue {
    pub value: f64,
    pub unit: String,
}

/// Réponse de `GET /v1/intensity/now`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct IntensityResponse {
    pub region: Region,
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub intensity: IntensityValue,
    pub methodology: Methodology,
    pub methodology_version: u32,
    /// Étiquette de révision de la mesure (ADR-0006) — pas un horodatage,
    /// voir le commentaire de module.
    pub vintage: String,
}

/// Réponse de `GET /v1/intensity/now/all` — dernière mesure de **chaque**
/// région disposant d'une donnée, national puis les 12 régions dans l'ordre de
/// `GET /v1/regions` (une région sans donnée est omise ; liste vide possible).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct IntensityAllResponse {
    /// Méthodologie servie — identique au champ `methodology` de chaque entrée
    /// (`rte-direct` n'existe qu'au national : une seule entrée).
    pub methodology: Methodology,
    pub methodology_version: u32,
    /// Nombre d'entrées de `regions` (1 à 13).
    pub count: u32,
    pub regions: Vec<IntensityResponse>,
}

/// Un point de `GET /v1/intensity/date` (`HistoryResponse::data`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct HistoryPoint {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub intensity: f64,
    pub vintage: String,
}

/// Réponse de `GET /v1/intensity/date`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct HistoryResponse {
    pub region: Region,
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub to: OffsetDateTime,
    pub unit: String,
    pub methodology: Methodology,
    pub count: u32,
    pub data: Vec<HistoryPoint>,
}

/// Un seau agrégé de `GET /v1/intensity/stats?interval=` (`StatsResponse::intervals`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct StatsBucket {
    #[serde(with = "time::serde::rfc3339")]
    pub start: OffsetDateTime,
    pub average: f64,
    pub min: f64,
    pub max: f64,
    pub count: u64,
}

/// Réponse de `GET /v1/intensity/stats`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct StatsResponse {
    pub region: Region,
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub to: OffsetDateTime,
    pub unit: String,
    pub methodology: Methodology,
    pub average: f64,
    pub min: f64,
    pub max: f64,
    pub count: u64,
    /// Pas d'agrégation demandé (`?interval=`), `None` si absent de la requête.
    pub interval: Option<Interval>,
    /// Série agrégée par seau, `None` si `interval` n'a pas été demandé.
    pub intervals: Option<Vec<StatsBucket>>,
}

/// Un créneau (`GET /v1/schedule/slots`, `GET /v1/intensity/below`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct SlotBody {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub intensity: f64,
}

/// Réponse d'une liste de créneaux (`GET /v1/schedule/slots`,
/// `GET /v1/intensity/below`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct SlotsResponse {
    pub region: Region,
    pub methodology: Methodology,
    /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
    pub model: String,
    pub estimator: Estimator,
    pub unit: String,
    pub count: u32,
    pub slots: Vec<SlotBody>,
}

// --- Prévision (`/v1/intensity/forecast`, `/v1/intensity/greenest-window`) -

/// Un point de `GET /v1/intensity/forecast` (`ForecastResponse::data`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ForecastPointBody {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub expected: f64,
    pub lower: f64,
    pub upper: f64,
}

/// Réponse de `GET /v1/intensity/forecast`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ForecastResponse {
    pub region: Region,
    pub methodology: Methodology,
    /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
    pub model: String,
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    pub horizon_hours: u32,
    pub unit: String,
    pub count: u32,
    pub data: Vec<ForecastPointBody>,
}

/// Un signal d'un créneau (`EligibilitySlotBody::signals`, ADR-0025/0026).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct EligibilitySignalBody {
    /// Pilier évalué (`renewable-share`, `surplus-price`,
    /// `low-carbon-intensity`) — `String`, pas dans le périmètre des enums
    /// dupliqués (voir le commentaire de module).
    pub pillar: String,
    pub verdict: EligibilitySignalVerdict,
    /// `regulatory`, `indicative-non-regulatory` ou `user-override` — `String`,
    /// même raison que `pillar`.
    pub basis: String,
    pub provenance: Option<EligibilitySignalProvenance>,
    /// Pourquoi le pilier est `indeterminate` (`missing-data`,
    /// `beyond-calibrated-horizon`…), absent sinon.
    pub reason: Option<String>,
    pub threshold: Option<f64>,
    pub value: Option<f64>,
    pub value_lower: Option<f64>,
    pub value_upper: Option<f64>,
}

/// Verdict d'éligibilité d'un créneau (`EligibilityBody::slots`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct EligibilitySlotBody {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub eligible: bool,
    pub intensity: f64,
    pub intensity_lower: f64,
    pub intensity_upper: f64,
    /// Score de classement **interne au cadre** — jamais comparable entre
    /// `framework`s (utiliser `intensity` pour ça).
    pub score: f64,
    pub signals: Vec<EligibilitySignalBody>,
}

/// Meilleur créneau éligible (`EligibilityBody::best_eligible`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct EligibleSlotBody {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub intensity: f64,
    pub intensity_lower: f64,
    pub intensity_upper: f64,
    pub score: f64,
}

/// Overlay d'éligibilité électrolyseur (`GreenestWindowResponse::eligibility`,
/// présent seulement si `?eligibility=` a été fourni).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct EligibilityBody {
    pub framework: EligibilityFramework,
    pub ruleset_version: String,
    pub ruleset_status: String,
    /// `true` si des overrides utilisateur (`surplus_price_eur_mwh`…) ont été
    /// appliqués au ruleset servi.
    pub overridden: bool,
    /// Zone de dépôt : toujours `FR` (jamais une sous-région).
    pub bidding_zone: String,
    pub disclaimer: String,
    pub window_eligible: bool,
    pub count_eligible: u32,
    pub count_indeterminate: u32,
    pub slots: Vec<EligibilitySlotBody>,
    pub best_eligible: Option<EligibleSlotBody>,
    /// Identité versionnée du modèle de part renouvelable prévue
    /// (`share-clim@1`), présente seulement si au moins un créneau est en
    /// provenance `forecast`.
    pub share_model: Option<String>,
}

/// Réponse de `GET /v1/intensity/greenest-window`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct GreenestWindowResponse {
    pub region: Region,
    pub methodology: Methodology,
    /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
    pub model: String,
    #[serde(with = "time::serde::rfc3339")]
    pub start: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub end: OffsetDateTime,
    pub unit: String,
    pub average_intensity: f64,
    /// Overlay d'éligibilité électrolyseur (présent uniquement si
    /// `?eligibility=` a été fourni) — annotation additive, la fenêtre verte
    /// elle-même est inchangée.
    pub eligibility: Option<EligibilityBody>,
}

// --- Scheduling (`/v1/schedule`, `/v1/schedule/slots`) ---------------------

/// Économie carbone d'un créneau planifié vs « maintenant » (ADR-0014).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct SavingsBody {
    pub now: f64,
    pub scheduled: f64,
    pub intensity_delta: f64,
    pub reduction_percent: f64,
    /// Économie absolue (gCO₂eq), seulement si `energy_kwh` a été fourni à la
    /// requête.
    pub absolute_saved_g: Option<f64>,
}

/// Réponse de `GET /v1/schedule`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ScheduleResponse {
    pub region: Region,
    pub methodology: Methodology,
    pub model: String,
    pub estimator: Estimator,
    pub unit: String,
    #[serde(with = "time::serde::rfc3339")]
    pub start: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub end: OffsetDateTime,
    pub average_intensity: f64,
    pub savings: SavingsBody,
}

// --- Mix de production (`/v1/mix`) -----------------------------------------

/// Mix de production par filière (`MixResponse::mix`), en MW.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
pub struct MixBody {
    pub nucleaire: f64,
    pub gaz: f64,
    pub charbon: f64,
    pub fioul: f64,
    pub hydraulique: f64,
    pub eolien: f64,
    pub solaire: f64,
    pub bioenergies: f64,
    pub pompage: f64,
    pub echanges: f64,
    /// Thermique fossile agrégé — **mix régional uniquement**, `None` au
    /// national.
    pub thermique: Option<f64>,
}

/// Part d'une filière dans la production (`MixResponse::shares`). Même forme
/// que [`PriceMixShareBody`] (contexte de `/v1/price`, un seul composant
/// OpenAPI côté serveur) — type distinct pour ne pas changer celui d'un champ
/// public déjà publié.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct MixShareBody {
    /// Slug de filière (`nucleaire`, `thermique`…) — `String`, catalogue
    /// `#[non_exhaustive]` côté serveur (voir le commentaire de module).
    pub filiere: String,
    pub label: String,
    /// Part dans la production, dans `[0, 1]` (somme = 1).
    pub share: f64,
    pub output_mw: f64,
}

/// Réponse de `GET /v1/mix`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct MixResponse {
    pub region: Region,
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub unit: String,
    pub mix: MixBody,
    /// Parts de production par filière (filières à production nulle omises,
    /// pompage/échanges exclus, `thermique` agrégé au régional). **Vide** face à
    /// un serveur plus ancien qui ne sert pas encore ce champ.
    #[serde(default)]
    pub shares: Vec<MixShareBody>,
}

// --- Échanges transfrontaliers (`/v1/exchanges*`) ---------------------------

/// Une frontière (`ExchangesResponse::exchanges`) : flux net signé FR↔voisin
/// + intensité carbone du voisin.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ExchangeEntry {
    /// Code du voisin (`be`, `de-lu`, `es`, `it-north`, `ch`, `gb`).
    pub country: String,
    pub country_name: String,
    /// Flux net (MW) : `> 0` = la France **importe**, `< 0` = exporte.
    pub flow_mw: f64,
    pub direction: FlowDirection,
    pub intensity: IntensityValue,
}

/// Réponse de `GET /v1/exchanges`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ExchangesResponse {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub net_flow_mw: f64,
    pub direction: FlowDirection,
    pub imports_mw: f64,
    pub exports_mw: f64,
    pub exchanges: Vec<ExchangeEntry>,
}

/// Réponse de `GET /v1/exchanges/date`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct ExchangesHistoryResponse {
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub to: OffsetDateTime,
    pub count: u32,
    pub snapshots: Vec<ExchangesResponse>,
}

// --- Météo (`/v1/weather*`) --------------------------------------------------

/// Un créneau météo (`WeatherHistoryResponse::points`), vent à 100 m +
/// irradiance, moyenne nationale.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct WeatherPoint {
    #[serde(with = "time::serde::rfc3339")]
    pub valid_at: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub run_at: OffsetDateTime,
    pub wind_kmh: f64,
    pub irradiance_wm2: f64,
}

/// Réponse de `GET /v1/weather`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct WeatherResponse {
    /// Attribution de la source (Open-Meteo, licence CC-BY 4.0).
    pub source: String,
    #[serde(with = "time::serde::rfc3339")]
    pub valid_at: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub run_at: OffsetDateTime,
    pub wind_kmh: f64,
    pub irradiance_wm2: f64,
}

/// Réponse de `GET /v1/weather/date`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct WeatherHistoryResponse {
    pub source: String,
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub to: OffsetDateTime,
    pub count: u32,
    pub points: Vec<WeatherPoint>,
}

// --- Renouvelable estimé (`/v1/renewable`) ----------------------------------

/// Capacités effectives calibrées (`RenewableResponse::model`, transparence
/// du modèle).
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
pub struct RenewableModelInfo {
    pub wind_capacity_mw: f64,
    pub solar_capacity_mw: f64,
}

/// Réponse de `GET /v1/renewable`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct RenewableResponse {
    /// Attribution (météo Open-Meteo CC-BY 4.0 ; valeurs modélisées).
    pub source: String,
    #[serde(with = "time::serde::rfc3339")]
    pub at: OffsetDateTime,
    pub wind_mw: f64,
    pub solar_mw: f64,
    pub wind_capacity_factor: f64,
    pub solar_capacity_factor: f64,
    pub model: RenewableModelInfo,
}

// --- Méthodologies et facteurs (`/v1/methodologies`, `/v1/factors`) --------

/// Une méthodologie du catalogue (`MethodologiesResponse::methodologies`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct MethodologyInfo {
    /// Identifiant stable (`rte-direct`, `acv-ademe`…) — `String` et pas
    /// [`Methodology`] : catalogue de découverte, peut lister une méthode
    /// `planned` non encore sélectionnable (voir le commentaire de module).
    pub id: String,
    pub version: u32,
    pub basis: String,
    pub scope: String,
    /// `true` si servie par défaut quand `?methodology=` est absent.
    pub default: bool,
    /// `served` (interrogeable) ou `planned` (spécifiée, pas encore servie).
    pub status: String,
    pub adr: String,
    pub description: String,
}

/// Réponse de `GET /v1/methodologies`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct MethodologiesResponse {
    pub methodologies: Vec<MethodologyInfo>,
}

/// Une région servie (`RegionsResponse::regions`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct RegionInfo {
    /// Slug stable — la valeur du paramètre `region` ([`Region`] tolère un
    /// futur slug inconnu via `Region::Other`).
    pub slug: Region,
    pub label: String,
    /// Code INSEE de la région métropolitaine ; `None` pour `national`.
    pub insee_code: Option<String>,
    /// `true` pour la maille nationale.
    pub national: bool,
}

/// Réponse de `GET /v1/regions` — catalogue statique : national puis les 12
/// régions métropolitaines (même ordre que `GET /v1/intensity/now/all`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct RegionsResponse {
    pub regions: Vec<RegionInfo>,
}

/// Un facteur d'émission par filière (`FactorsResponse::factors`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct FactorEntry {
    /// Filière (`nucleaire`, `gaz`…) — `String`, pas dans le périmètre des
    /// enums dupliqués.
    pub filiere: String,
    /// Facteur cycle de vie (gCO₂eq/kWh).
    pub factor: f64,
}

/// Réponse de `GET /v1/factors`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct FactorsResponse {
    pub methodology: Methodology,
    pub methodology_version: u32,
    pub unit: String,
    pub source: String,
    /// Facteur de pertes T&D appliqué, `None` hors méthode consommation.
    pub td_loss_factor: Option<f64>,
    pub factors: Vec<FactorEntry>,
}

// --- Prix (`/v1/price*`, `/v1/cost-reference`) ------------------------------

/// Une composante du prix (`PriceResponse::components`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PriceComponentBody {
    /// Identifiant stable (`energie`, `acheminement`, `accise`,
    /// `commercialisation`, `tva`) — `String`, pas dans le périmètre des
    /// enums dupliqués.
    pub kind: String,
    pub label: String,
    pub amount_eur_mwh: f64,
    /// Source / fondement réglementaire de la composante.
    pub source: String,
}

/// Part d'une filière dans le mix (`PriceContextBody::mix`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PriceMixShareBody {
    pub filiere: String,
    pub label: String,
    /// Part dans la production domestique, dans `[0, 1]`.
    pub share: f64,
    pub output_mw: f64,
}

/// Technologie marginale **estimée** (`PriceContextBody::marginal_technology`,
/// ordre de mérite domestique — jamais mesurée, `estimated` vaut toujours
/// `true`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct MarginalTechnologyBody {
    pub filiere: String,
    pub label: String,
    pub estimated: bool,
    /// Méthode d'estimation (transparence).
    pub method: String,
}

/// Contexte explicatif du prix (`PriceResponse::context`, ADR-0023 §4).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PriceContextBody {
    pub mix: Vec<PriceMixShareBody>,
    pub marginal_technology: Option<MarginalTechnologyBody>,
}

/// Réponse de `GET /v1/price`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PriceResponse {
    pub region: Region,
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    /// Millésime de la construction réglementaire en vigueur à cet
    /// horodatage (ex. `2026-H2`) — `String`, pas un instant RFC 3339 (voir
    /// le commentaire de module).
    pub vintage: String,
    pub unit: String,
    pub currency: String,
    pub total_eur_mwh: f64,
    pub total_eur_kwh: f64,
    pub components: Vec<PriceComponentBody>,
    pub context: PriceContextBody,
    pub disclaimer: String,
}

/// Un point compact de `GET /v1/price/date` (`PriceHistoryResponse::points`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PricePointBody {
    #[serde(with = "time::serde::rfc3339")]
    pub timestamp: OffsetDateTime,
    pub energie_eur_mwh: f64,
    pub total_eur_mwh: f64,
}

/// Réponse de `GET /v1/price/date`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct PriceHistoryResponse {
    #[serde(with = "time::serde::rfc3339")]
    pub from: OffsetDateTime,
    #[serde(with = "time::serde::rfc3339")]
    pub to: OffsetDateTime,
    pub count: u32,
    pub unit: String,
    pub currency: String,
    pub points: Vec<PricePointBody>,
}

/// Hypothèses d'une estimation LCOE (`CostReferenceEntry::hypotheses`),
/// `None` = « non publié par la source », jamais une dimension retirée.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
pub struct CostAssumptionsBody {
    pub discount_rate: Option<f64>,
    pub lifetime_years: Option<u32>,
    pub load_factor: Option<f64>,
}

/// Fourchette d'une estimation LCOE (`CostReferenceEntry::range`).
#[derive(Debug, Clone, PartialEq, Deserialize)]
pub struct LcoeRangeBody {
    pub min: f64,
    pub median: f64,
    pub max: f64,
    pub unit: String,
}

/// Une estimation LCOE (source × technologie × périmètre × millésime,
/// `CostReferenceResponse::entries`, ADR-0024). Champs catalogue
/// (`technology`/`source`/`perimeter`/`basis`) en `String` : hors du
/// périmètre des enums dupliqués par cette mission.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct CostReferenceEntry {
    pub technology: String,
    pub technology_label: String,
    pub source: String,
    pub source_label: String,
    pub source_attribution: String,
    /// `france` ou `monde` — les valeurs IRENA sont **mondiales**.
    pub geography: String,
    pub perimeter: String,
    pub perimeter_label: String,
    /// `accounting-amortized` (coût comptable) vs `prospective-lcoe`
    /// (moyen neuf).
    pub basis: String,
    pub basis_label: String,
    /// Nombre de sources distinctes pour cette filière (≥ 2 = dispersion
    /// inter-sources).
    pub technology_source_count: u32,
    /// Millésime (année du rapport source) — entier, distinct de
    /// `HistoryPoint::vintage`/`IntensityResponse::vintage` (étiquette de
    /// révision, pas un millésime).
    pub vintage: u32,
    /// Statut : toujours `estimation` (ADR-0024 §4).
    pub kind: String,
    pub range: LcoeRangeBody,
    pub hypotheses: CostAssumptionsBody,
}

/// Réponse de `GET /v1/cost-reference` — couche comparative LCOE (ADR-0024).
/// **Estimation**, en fourchette, jamais mise en différence avec le prix de
/// marché (`disclaimer` obligatoire, ADR-0024 §3).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct CostReferenceResponse {
    pub unit: String,
    pub currency: String,
    /// Statut systématique de la couche : `estimation`.
    pub kind: String,
    pub disclaimer: String,
    pub count: u32,
    pub entries: Vec<CostReferenceEntry>,
}

// --- Éligibilité (`/v1/eligibility/rulesets`) -------------------------------

/// Une entrée du catalogue (`RulesetsResponse::rulesets`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct RulesetInfo {
    pub framework: EligibilityFramework,
    pub version: String,
    /// `served` (appliqué) ou `planned` (réservé, texte non adopté).
    pub status: String,
    pub adr: String,
    /// Granularité de corrélation temporelle (pilier `rfnbo`) ;
    /// `n/a (pilier rfnbo)` pour `low-carbon`.
    pub granularity: String,
    /// Seuil renouvelable de l'exception Article 4 (`rfnbo` uniquement).
    pub article4_renewable_threshold: Option<f64>,
    pub surplus_price_eur_mwh: Option<f64>,
    /// Date de bascule horaire (`rfnbo`), ex. `2030-01-01` — **date seule**,
    /// pas un instant RFC 3339 (voir le commentaire de module), `None` pour
    /// `low-carbon`.
    pub hourly_switchover: Option<String>,
    pub low_carbon_intensity_threshold_g_per_kwh: Option<f64>,
    pub low_carbon_intensity_is_indicative: bool,
    /// Consommation électrolyseur qui dérive le seuil (`low-carbon`
    /// uniquement).
    pub electrolyzer_kwh_per_kg: Option<f64>,
    pub legal_basis: String,
    pub description: String,
}

/// Réponse de `GET /v1/eligibility/rulesets`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct RulesetsResponse {
    pub rulesets: Vec<RulesetInfo>,
    pub disclaimer: String,
}

// --- Statistiques de visite (`/v1/stats`, `POST /v1/stats/visit`) ----------

/// Réponse de `GET /v1/stats` et `POST /v1/stats/visit`.
#[derive(Debug, Clone, PartialEq, Deserialize)]
pub struct VisitStatsResponse {
    pub unique: u64,
    pub total: u64,
    /// Premier jour comptabilisé, `ISO YYYY-MM-DD` — **date seule**, pas un
    /// instant RFC 3339 (voir le commentaire de module), `None` si aucun.
    pub since: Option<String>,
}

// --- Webhooks (`/v1/webhooks*`) --------------------------------------------

/// Corps de `POST /v1/webhooks` (ADR-0016).
#[derive(Debug, Clone, Serialize, PartialEq)]
pub struct CreateWebhookRequest {
    /// Seuil d'intensité (gCO₂eq/kWh).
    pub threshold: f64,
    pub direction: ThresholdDirection,
    /// URL HTTPS de rappel (validée anti-SSRF côté serveur).
    pub callback_url: String,
    /// Région à surveiller. National par défaut si `None`.
    pub region: Option<Region>,
}

/// Réponse de création : inclut le **secret** (affiché une seule fois,
/// jamais ré-exposé par `GET /v1/webhooks`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct CreatedWebhookResponse {
    pub id: String,
    /// Secret de signature HMAC — à conserver, non ré-affiché.
    pub secret: String,
    pub region: Region,
    pub threshold: f64,
    pub direction: ThresholdDirection,
    pub callback_url: String,
}

/// Résumé d'un abonnement, sans le secret (`WebhookListResponse::webhooks`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct WebhookSummary {
    pub id: String,
    pub region: Region,
    pub threshold: f64,
    pub direction: ThresholdDirection,
    pub callback_url: String,
    pub status: WebhookStatus,
    /// Instant de la désactivation automatique, `None` si actif.
    #[serde(with = "time::serde::rfc3339::option")]
    pub disabled_at: Option<OffsetDateTime>,
}

/// Réponse de `GET /v1/webhooks`.
#[derive(Debug, Clone, Deserialize, PartialEq)]
pub struct WebhookListResponse {
    pub count: u32,
    pub webhooks: Vec<WebhookSummary>,
}