{"_id":"@carbon-fr/sdk","_rev":"3-9131b1c7e4e409269cee5aed273413c5","name":"@carbon-fr/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@carbon-fr/sdk","version":"0.1.0","keywords":["carbon","electricity","france","co2","rte","eco2mix","api","sdk"],"license":"MIT OR Apache-2.0","_id":"@carbon-fr/sdk@0.1.0","maintainers":[{"name":"microlaxe","email":"morgan.voltz@kovelt.fr"}],"homepage":"https://github.com/Kovelt/carbon-fr","bugs":{"url":"https://github.com/Kovelt/carbon-fr/issues"},"dist":{"shasum":"60323ad00cff487fc610ab42df4fa28caad6d363","tarball":"https://registry.npmjs.org/@carbon-fr/sdk/-/sdk-0.1.0.tgz","fileCount":17,"integrity":"sha512-1juAWbJmBLMFzM41xJe54LfALKhKOeHbeeOKx8B18fpEQ6jyZF14ICuDkBwe0w/y6pWiTkT9jHwHaNVzFElItw==","signatures":[{"sig":"MEUCICM1dN0A9LsWplaRqMfnse0T7Pm0BH8lwIYtXEnxbeJcAiEAgTBBEV7mSBCBPdrC2y01ZKIHbtU08DOGig39lKmUzC4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@carbon-fr%2fsdk@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":69166},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a6a8b3e03af927dbb69bd744818eadabf97fb907","scripts":{"build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"microlaxe","email":"morgan.voltz@kovelt.fr"},"repository":{"url":"git+https://github.com/Kovelt/carbon-fr.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"10.8.2","description":"Client TypeScript de l'API carbon-fr — intensité carbone de l'électricité française (gCO₂eq/kWh).","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1781623936825_0.8755356939859087","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@carbon-fr/sdk","version":"0.2.0","keywords":["carbon","electricity","france","co2","rte","eco2mix","api","sdk"],"license":"MIT OR Apache-2.0","_id":"@carbon-fr/sdk@0.2.0","maintainers":[{"name":"microlaxe","email":"morgan.voltz@kovelt.fr"}],"homepage":"https://github.com/Kovelt/carbon-fr","bugs":{"url":"https://github.com/Kovelt/carbon-fr/issues"},"dist":{"shasum":"8509446643fe17016ee8d67a5da3b3324ca443ad","tarball":"https://registry.npmjs.org/@carbon-fr/sdk/-/sdk-0.2.0.tgz","fileCount":17,"integrity":"sha512-0xzyhGc2Zz3HQ7On96S5EoI9ahLn+u/sBXTiHLxVy93dOpOBJF01QyUMhW+mm5ycELnQVTlfLpawZyjYDwHELQ==","signatures":[{"sig":"MEUCIB4kt0pKHtfUeRcdtkMVuAe8Dm7rTAMokMFp1NJom9iFAiEAjSYjcvSSshavMm8WYzS3ngZtnc/mMXqaAgVXyA0lERU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIE0hNfOnNf/9wt+b2+We5eBWEGTwN0OmhguosFKQQjK5AiEA3vjSCJyAhxNxvwuf1ohBPkhVtYd2dkQhrWFtuNW3c0k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@carbon-fr%2fsdk@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":100353},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d8b50cc187d05113f83e2d3a91898151f71b2b36","scripts":{"build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:51f7a747-4aff-41fa-bc21-b7c625a2b93a"}},"repository":{"url":"git+https://github.com/Kovelt/carbon-fr.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"12.1.0","description":"Client TypeScript de l'API carbon-fr — intensité carbone de l'électricité française (gCO₂eq/kWh).","directories":{},"sideEffects":false,"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1790166535022_0.5685822232539965","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@carbon-fr/sdk@0.3.0","bugs":{"url":"https://github.com/Kovelt/carbon-fr/issues"},"dist":{"shasum":"629e4dc1f5efc46354ab7ea95f443a974fe9a249","tarball":"https://registry.npmjs.org/@carbon-fr/sdk/-/sdk-0.3.0.tgz","fileCount":17,"integrity":"sha512-qzIhayvtWr3cisZFr9PXtNQyH9vsriwvCSQ2cR4djqxin9I6dyvEFXdOicm5k9/cvAMhR0OaG0DO/C4/bIaKYg==","signatures":[{"sig":"MEUCIAzdN/+DiS9Z8vkAMxzFd0XQn58YLXmArwOnYXwBjh1yAiEAsEk6it+lejfgE/mPmz4Is6HP47BxFAfFKg8wr34gehU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCYt+HJ3CNMNtSJOhlE8mQE6cVhnHDflOUYDnha3IMk7AIhANE6lkHD4dDqbbRmnjl9la/XSoaZqvfAUSyoCe57o+a0"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@carbon-fr%2fsdk@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":106574},"main":"./dist/index.js","name":"@carbon-fr/sdk","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"671726bab0a222c52baf23d439ad3f670e4a778d","license":"MIT OR Apache-2.0","scripts":{"build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:51f7a747-4aff-41fa-bc21-b7c625a2b93a"}},"homepage":"https://github.com/Kovelt/carbon-fr","keywords":["carbon","electricity","france","co2","rte","eco2mix","api","sdk"],"repository":{"url":"git+https://github.com/Kovelt/carbon-fr.git","type":"git","directory":"sdk/typescript"},"_npmVersion":"12.1.0","description":"Client TypeScript de l'API carbon-fr — intensité carbone de l'électricité française (gCO₂eq/kWh).","directories":{},"maintainers":[{"name":"microlaxe","email":"morgan.voltz@kovelt.fr"}],"sideEffects":false,"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1790544252843_0.27791829811134594"}}},"time":{"created":"2026-06-16T15:32:16.549Z","modified":"2026-09-27T21:24:13.248Z","0.1.0":"2026-06-16T15:32:17.036Z","0.2.0":"2026-09-23T12:28:55.114Z","0.3.0":"2026-09-27T21:24:12.918Z"},"bugs":{"url":"https://github.com/Kovelt/carbon-fr/issues"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/Kovelt/carbon-fr","keywords":["carbon","electricity","france","co2","rte","eco2mix","api","sdk"],"repository":{"url":"git+https://github.com/Kovelt/carbon-fr.git","type":"git","directory":"sdk/typescript"},"description":"Client TypeScript de l'API carbon-fr — intensité carbone de l'électricité française (gCO₂eq/kWh).","maintainers":[{"name":"microlaxe","email":"morgan.voltz@kovelt.fr"}],"readme":"# @carbon-fr/sdk\n\nClient **TypeScript** de l'API [carbon-fr](https://github.com/Kovelt/carbon-fr) — l'intensité carbone de l'électricité française (gCO₂eq/kWh), souveraine et _dev-first_.\n\n- **Zéro dépendance runtime** (utilise `fetch` natif — navigateur, Node ≥ 22, Deno, Bun). Node 22 est le plancher testé en CI (plus ancienne LTS maintenue) ; le code n'utilise que `fetch`, disponible dès Node 18.\n- **Typé de bout en bout** : chaque endpoint de **données** `/v1` a sa méthode et son type de réponse (les endpoints d'exploitation/spec — `/health`, `/metrics`, `/v1/openapi.json` — ne sont pas exposés).\n- **Flux live** (SSE) exposé en `AsyncGenerator`.\n\n> **Versions** : ce README documente la **0.2.0** (publiée sur npm par le tag `sdk-v0.2.0`). La 0.1.0 n'expose ni `price`/`priceHistory`, ni `costReference`, ni `eligibilityRulesets`, ni l'option `eligibility` de `greenestWindow` — vérifier la version installée (`npm view @carbon-fr/sdk version`).\n\n## Installation\n\n```bash\nnpm install @carbon-fr/sdk\n```\n\n## Démarrage\n\n```ts\nimport { CarbonFr } from \"@carbon-fr/sdk\";\n\nconst cf = new CarbonFr(); // instance hébergée par défaut\n\n// Intensité courante (national, rte-direct)\nconst now = await cf.intensityNow();\nconsole.log(now.intensity.value, now.intensity.unit); // 14 gCO2eq/kWh\n\n// Mix d'une région\nconst mix = await cf.mix({ region: \"bretagne\" });\n\n// acv-ademe consumption-based (imports inclus, national)\nconst conso = await cf.intensityNow({ methodology: \"acv-ademe\", version: 2 });\n\n// Prévision avec intervalle d'incertitude\nconst fc = await cf.forecast({ horizonHours: 24 });\nfor (const p of fc.data) console.log(p.timestamp, p.lower, p.expected, p.upper);\n\n// Échanges transfrontaliers (carte des voisins)\nconst ex = await cf.exchanges();\nfor (const c of ex.exchanges) console.log(c.country_name, c.flow_mw, c.intensity.value);\n\n// Renouvelable estimé depuis la météo (facteur de charge)\nconst ren = await cf.renewable();\nconsole.log(`éolien ${(ren.wind_capacity_factor * 100).toFixed(0)}% de capacité`);\n\n// Éligibilité électrolyseur : fenêtre verte annotée RFNBO ou bas-carbone (ADR-0025/0026)\nconst win = await cf.greenestWindow({ horizonHours: 24, eligibility: \"low-carbon\" });\nconsole.log(win.eligibility?.window_eligible, win.eligibility?.count_eligible);\nfor (const s of win.eligibility?.slots ?? []) console.log(s.timestamp, s.eligible, s.score);\n\n// Catalogue des cadres d'éligibilité (rulesets versionnés, seuils, base légale)\nconst rs = await cf.eligibilityRulesets();\nfor (const r of rs.rulesets) console.log(r.version, r.status, r.legal_basis);\n```\n\n## Flux temps réel (SSE)\n\n```ts\nconst ac = new AbortController();\nfor await (const e of cf.stream({ below: 50, signal: ac.signal })) {\n  console.log(e.timestamp, e.intensity);\n}\n// ac.abort() pour arrêter.\n```\n\n## Configuration\n\n```ts\nconst cf = new CarbonFr({\n  baseUrl: \"https://carbon-fr-api.kovelt.fr\", // défaut\n  apiKey: \"…\",   // requis seulement pour les webhooks / quota du tier hébergé\n  fetch: customFetch, // optionnel (Node < 18, mocks de test)\n});\n```\n\n## Endpoints couverts\n\n| Méthode | Endpoint |\n| --- | --- |\n| `intensityNow` | `GET /v1/intensity/now` |\n| `intensityNowAll` | `GET /v1/intensity/now/all` (les 13 régions en un appel ; `methodology: \"acv-ademe\"` — `rte-direct` n'existe qu'au national) |\n| `mix` | `GET /v1/mix` (MW par filière + parts `shares`) |\n| `intensityDate` | `GET /v1/intensity/date` |\n| `intensityStats` | `GET /v1/intensity/stats` |\n| `forecast` | `GET /v1/intensity/forecast` |\n| `greenestWindow` | `GET /v1/intensity/greenest-window` (overlay électrolyseur via `eligibility: \"rfnbo\" \\| \"low-carbon\"` + overrides) |\n| `eligibilityRulesets` | `GET /v1/eligibility/rulesets` (cadres d'éligibilité électrolyseur) |\n| `schedule` · `scheduleSlots` · `below` | scheduling carbon-aware |\n| `exchanges` · `exchangesHistory` | `GET /v1/exchanges[/date]` |\n| `weather` · `weatherHistory` | `GET /v1/weather[/date]` |\n| `renewable` | `GET /v1/renewable` |\n| `methodologies` · `factors` · `regions` | méthodes, facteurs & catalogue des régions (`GET /v1/regions`) |\n| `price` · `priceHistory` | `GET /v1/price[/date]` (décomposition TRV, national uniquement — `region` accepté mais toute valeur non nationale renvoie une 400) |\n| `costReference` | `GET /v1/cost-reference` (LCOE, estimation) |\n| `visitStats` · `recordVisit` | compteur RGPD-friendly |\n| `createWebhook` · `listWebhooks` · `deleteWebhook` | webhooks (clé API) |\n| `stream` | `GET /v1/intensity/stream` (SSE) |\n\n## Gestion d'erreurs\n\nToute réponse non-2xx lève une `CarbonFrError` (`.status`, `.code`, `.message`) :\n\n```ts\nimport { CarbonFrError } from \"@carbon-fr/sdk\";\n\ntry {\n  await cf.intensityNow({ region: \"atlantide\" });\n} catch (e) {\n  if (e instanceof CarbonFrError) console.error(e.status, e.code, e.message);\n}\n```\n\n## Licence\n\nMIT OU Apache-2.0, au choix.\n","readmeFilename":"README.md"}