Skip to main content

Crate carbonfr_sdk

Crate carbonfr_sdk 

Source
Expand description

§carbonfr-sdk

Client Rust asynchrone (tokio) de l’API carbon-fr — intensité carbone de l’électricité française (gCO₂eq/kWh), temps réel et historique.

use carbonfr_sdk::{CarbonFr, IntensityStreamOptions};
use futures_util::StreamExt;

let client = CarbonFr::builder().build()?;
let mut stream = client.intensity_stream(IntensityStreamOptions::default())?;
while let Some(event) = stream.next().await {
    println!("{:?}", event?);
}

§Couverture

Parité avec les 29 opérations /v1 du SDK TypeScript 0.5.0 (ADR-0031 décision 8 ; health/health_ready, d’exploitation, ne sont pas exposées) : construction du client (CarbonFr/CarbonFrBuilder), erreurs typées (CarbonFrError, RFC 9457), 28 méthodes REST (ex. CarbonFr::intensity_now, CarbonFr::mix, CarbonFr::schedule, CarbonFr::create_webhook…) et le flux SSE CarbonFr::intensity_stream (feature Cargo stream). Exemples exécutables dans examples/ du dépôt.

§Construction TLS (ADR-0031 décision 3)

reqwest 0.13 sans provider crypto installé panique à la construction d’un client. Ce SDK ne s’appuie jamais sur un provider par défaut du processus (rustls::crypto::CryptoProvider::get_default() / install_default(), utilisés par bin/server et les adapters de ce dépôt) : il construit son propre rustls::ClientConfig avec le provider ring passé explicitement, et le donne à reqwest via ClientBuilder::tls_backend_preconfigured. Utilisable tel quel dans un process qui n’installe aucun provider par défaut — voir client::tests::crypto_provider_default_stays_uninstalled.

Structs§

BelowOptions
GET /v1/intensity/below — threshold (requis en pratique, cf. le commentaire de module) est un argument direct de crate::CarbonFr::below.
CarbonFr
Client de l’API carbon-fr (intensité carbone de l’électricité française).
CarbonFrBuilder
Construit un CarbonFr.
CostAssumptionsBody
Hypothèses d’une estimation LCOE (CostReferenceEntry::hypotheses), None = « non publié par la source », jamais une dimension retirée.
CostReferenceEntry
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.
CostReferenceOptions
GET /v1/cost-reference — filtres en String/u32 bruts : les valeurs possibles (source, technology, perimeter) ne sont pas dans le périmètre des enums dupliqués par cette mission (sdk-spec.json enums_to_duplicate).
CostReferenceResponse
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).
CreateWebhookRequest
Corps de POST /v1/webhooks (ADR-0016).
CreatedWebhookResponse
Réponse de création : inclut le secret (affiché une seule fois, jamais ré-exposé par GET /v1/webhooks).
EligibilityBody
Overlay d’éligibilité électrolyseur (GreenestWindowResponse::eligibility, présent seulement si ?eligibility= a été fourni).
EligibilitySignalBody
Un signal d’un créneau (EligibilitySlotBody::signals, ADR-0025/0026).
EligibilitySlotBody
Verdict d’éligibilité d’un créneau (EligibilityBody::slots).
EligibleSlotBody
Meilleur créneau éligible (EligibilityBody::best_eligible).
ExchangeEntry
Une frontière (ExchangesResponse::exchanges) : flux net signé FR↔voisin
ExchangesHistoryResponse
Réponse de GET /v1/exchanges/date.
ExchangesResponse
Réponse de GET /v1/exchanges.
FactorEntry
Un facteur d’émission par filière (FactorsResponse::factors).
FactorsOptions
GET /v1/factors.
FactorsResponse
Réponse de GET /v1/factors.
ForecastOptions
GET /v1/intensity/forecast.
ForecastPointBody
Un point de GET /v1/intensity/forecast (ForecastResponse::data).
ForecastResponse
Réponse de GET /v1/intensity/forecast.
GreenestWindowOptions
GET /v1/intensity/greenest-window.
GreenestWindowResponse
Réponse de GET /v1/intensity/greenest-window.
HistoryPoint
Un point de GET /v1/intensity/date (HistoryResponse::data).
HistoryResponse
Réponse de GET /v1/intensity/date.
IndexBand
Une bande du barème de l’index qualitatif (IntensityIndexResponse::bands), intervalle [min, max[ en gCO₂eq/kWh.
IndexThreshold
Une borne du barème et ce qui la fonde (IntensityIndexResponse::thresholds).
IntensityAllResponse
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).
IntensityDateOptions
GET /v1/intensity/date — from/to (requis) sont des arguments directs de crate::CarbonFr::intensity_date.
IntensityIndexResponse
Réponse de GET /v1/intensity/index — barème de l’index qualitatif (ADR-0033) : même rôle que /v1/factors pour l’ACV, la légende du champ index est auditable (bornes et sources) au lieu d’être codée en dur côté client. Serveur ≥ 0.11 (404 avant).
IntensityNowAllOptions
GET /v1/intensity/now/all — pas de région : toutes.
IntensityNowOptions
GET /v1/intensity/now.
IntensityResponse
Réponse de GET /v1/intensity/now.
IntensityStatsOptions
GET /v1/intensity/stats — from/to (requis) sont des arguments directs de crate::CarbonFr::intensity_stats.
IntensityValue
Valeur d’intensité carbone (IntensityResponse::intensity).
LcoeRangeBody
Fourchette d’une estimation LCOE (CostReferenceEntry::range).
MarginalTechnologyBody
Technologie marginale estimée (PriceContextBody::marginal_technology, ordre de mérite domestique — jamais mesurée, estimated vaut toujours true).
MethodologiesResponse
Réponse de GET /v1/methodologies.
MethodologyInfo
Une méthodologie du catalogue (MethodologiesResponse::methodologies).
MixBody
Mix de production par filière (MixResponse::mix), en MW.
MixOptions
GET /v1/mix.
MixResponse
Réponse de GET /v1/mix.
MixShareBody
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é.
PriceComponentBody
Une composante du prix (PriceResponse::components).
PriceContextBody
Contexte explicatif du prix (PriceResponse::context, ADR-0023 §4).
PriceHistoryOptions
GET /v1/price/date — from/to (requis) sont des arguments directs de crate::CarbonFr::price_history ; region, si fourni, doit être national (même remarque que PriceOptions).
PriceHistoryResponse
Réponse de GET /v1/price/date.
PriceMixShareBody
Part d’une filière dans le mix (PriceContextBody::mix).
PriceOptions
GET /v1/price — region, si fourni, doit être national (toute autre valeur renvoie 400, le TRV est national) : documenté ici comme côté SDK TS, pas imposé par un type dédié (le serveur reste la source de vérité).
PricePointBody
Un point compact de GET /v1/price/date (PriceHistoryResponse::points).
PriceResponse
Réponse de GET /v1/price.
ProblemDetails
Corps Problem Details (RFC 9457) porté par CarbonFrError::Api.
RegionInfo
Une région servie (RegionsResponse::regions).
RegionsResponse
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).
RenewableModelInfo
Capacités effectives calibrées (RenewableResponse::model, transparence du modèle).
RenewableResponse
Réponse de GET /v1/renewable.
RulesetInfo
Une entrée du catalogue (RulesetsResponse::rulesets).
RulesetsResponse
Réponse de GET /v1/eligibility/rulesets.
SavingsBody
Économie carbone d’un créneau planifié vs « maintenant » (ADR-0014).
ScheduleOptions
GET /v1/schedule.
ScheduleResponse
Réponse de GET /v1/schedule.
ScheduleSlotsOptions
GET /v1/schedule/slots — count (requis en pratique, cf. le commentaire de module) est un argument direct de crate::CarbonFr::schedule_slots.
SlotBody
Un créneau (GET /v1/schedule/slots, GET /v1/intensity/below).
SlotsResponse
Réponse d’une liste de créneaux (GET /v1/schedule/slots, GET /v1/intensity/below).
StatsBucket
Un seau agrégé de GET /v1/intensity/stats?interval= (StatsResponse::intervals).
StatsResponse
Réponse de GET /v1/intensity/stats.
VisitStatsResponse
Réponse de GET /v1/stats et POST /v1/stats/visit.
WeatherHistoryResponse
Réponse de GET /v1/weather/date.
WeatherPoint
Un créneau météo (WeatherHistoryResponse::points), vent à 100 m + irradiance, moyenne nationale.
WeatherResponse
Réponse de GET /v1/weather.
WebhookListResponse
Réponse de GET /v1/webhooks.
WebhookSummary
Résumé d’un abonnement, sans le secret (WebhookListResponse::webhooks).

Enums§

CarbonFrError
Erreur du SDK carbon-fr.
EligibilityFramework
Cadre d’éligibilité électrolyseur (ADR-0025/0026) : rfnbo (Règl. délégués UE 2023/1184-1185) ou low-carbon (Acte délégué UE 2025/2359). Deux piliers du droit européen tel qu’adopté ; une révision réglementaire (rfnbo:2026-revision, planned) reste une version du même cadre (RulesetInfo::version), pas un 3ᵉ cadre.
EligibilitySignalProvenance
Provenance de la valeur d’un signal d’éligibilité (EligibilitySignalBody::provenance, absente sur un signal indeterminate) : observed (donnée mesurée/publiée) ou forecast (prévision, share-clim@1). Ouverte (#[non_exhaustive] + EligibilitySignalProvenance::Other, comme crate::Region) : sdk-spec.json la marque open: true, contrairement aux autres enums de ce fichier.
EligibilitySignalVerdict
Verdict d’un signal d’éligibilité (EligibilitySignalBody::verdict, ADR-0025/0026) : pass, fail ou indeterminate (donnée manquante, jamais extrapolée).
Estimator
Estimateur d’intensité prévue (ADR-0009/0011) : central (estimation) ou prudent (borne haute de l’intervalle de confiance).
FlowDirection
Sens d’un flux transfrontalier (ExchangeEntry/ExchangesResponse, ADR-0017) — champ de réponse uniquement, jamais un paramètre de requête : import (> 0), export (< 0) ou balanced.
IntensityIndex
Index qualitatif d’une intensité carbone (ADR-0033, barème index@1) : cinq bandes absolues en gCO₂eq/kWh, séparées par les bornes 20 · 64,8 · 100 · 200 — basses incluses, hautes exclues ([a, b[ : 20 g est low, 19,9 g est very-low). Un seul barème pour toutes les méthodologies et toutes les régions ; le catalogue des bornes et de leurs sources est servi par GET /v1/intensity/index (CarbonFr::intensity_index).
Interval
Pas d’agrégation d’une série (GET /v1/intensity/stats?interval=) : hour ou day.
Methodology
Méthodologie de calcul de l’intensité carbone (ADR-0005) : rte-direct (national, taux CO₂ publié directement) ou acv-ademe (cycle de vie, national + 12 régions). Catalogue fini : une nouvelle méthodologie est un changement de méthodologie, donc un nouvel ADR (CONTRIBUTING.md) — exhaustif, pas #[non_exhaustive] (ADR-0030 §3).
Region
Région éCO2mix : national ou l’une des 12 régions métropolitaines, ou tout autre slug accepté/renvoyé par le serveur mais pas encore listé ici.
ThresholdDirection
Sens de franchissement d’un seuil (webhooks, ADR-0016) — paramètre de requête et champ de réponse (CreateWebhookRequest/WebhookSummary) : below ou above.
WebhookStatus
État d’un abonnement webhook (WebhookSummary::status, ADR-0016) : active, ou disabled (désactivé automatiquement après une série de livraisons échouées — le réactiver suppose de le supprimer puis le recréer, nouveau secret).

Constants§

DEFAULT_BASE_URL
URL de base de l’instance hébergée par défaut (ADR-0031).
DEFAULT_CONNECT_TIMEOUT
Délai par défaut d’établissement de connexion (cf. CarbonFrBuilder::connect_timeout) : pour le REST, TCP + TLS seulement (le reste de la requête relève de DEFAULT_TIMEOUT) ; pour le flux SSE, TCP + TLS + envoi de la requête + réception des en-têtes, le flux n’ayant ensuite aucun timeout total (ADR-0031, points tranchés 2026-09-25).
DEFAULT_TIMEOUT
Délai par défaut d’une requête REST (connexion + réponse) — écart assumé à la parité stricte avec le SDK TS, qui n’en a aucun (point tranché par Morgan le 2026-09-25, ADR-0031). Configurable (CarbonFrBuilder::timeout) et désactivable (CarbonFrBuilder::no_timeout).