Wants AI carbon and token figures inside an internal dashboard, next to cloud cost.
What they get: usage.getSummary and telemetry.getSummary return the same numbers the CrbonFree dashboard shows, typed.
@crbonfree/sdkv0.5.0Build on your numbers
Read your usage, emissions and receipts from TypeScript.
One typed client covers the twelve public API operations. It returns the numbers the backend has already computed, so a report, an internal dashboard or an automation shows the same figures your dashboard does.
Install and sign in
npm install @crbonfree/sdk && npx @crbonfree/sdk loginexample
4,500+
SDK and MCP downloads with no paid marketing
Crbon Labs, 2026
12
public read operations covered, one method each
4
sub-clients: projects, usage, telemetry, billing
203,000
verified credits issued, readable as receipts
Crbon Labs, 2026
What is the TypeScript SDK?
The CrbonFree TypeScript SDK, published as @crbonfree/sdk on npm, is a typed Node.js client for the twelve public read operations of the CrbonFree API. It returns usage totals, emissions with their uncertainty bounds, credit retirement receipts and audit packs that the backend has already computed, so a report, an internal dashboard or an automation shows the same figures as the CrbonFree dashboard.
Last checked against the product on 5 September 2026. Carbon figures follow methodology v1.2.
At a glance
- Package
- @crbonfree/sdk on npm
- Version
- 0.5.0
- Licence
- MIT
- Requires
- Node.js 18 or newer
- Authenticates with
- X-API-Key, keys start with ck_live_
- Credentials
- ~/.crbonfree/credentials, shared with the MCP server
- Operations
- 12 reads across projects, usage, telemetry and billing
- Generated from
- The OpenAPI spec, with Zod schemas
- Data direction
- Reads only
Four sub-clients, twelve read operations
projects, usage, telemetry and billing map one to one onto the public API. Usage returns totals, a per-model breakdown, daily rows and a CSV or JSON export. Telemetry returns CO2e with upper and lower bounds and every provider and model seen. Billing returns the retirement status of the current period, the receipts and the monthly audit packs.
Sign in once from the terminal
npx @crbonfree/sdk login opens the browser, generates an API key and saves it to ~/.crbonfree/credentials, so the constructor needs no arguments. The Python SDK and the MCP server read the same file, and one sign-in covers all three. In CI you set CRBONFREE_API_KEY or pass apiKey to the constructor instead.
Types generated from the API spec
The client is generated from the backend’s OpenAPI specification, so every response is typed and each error status has its own class, from BadRequestError to TooManyRequestsError. Zod schemas ship in the package under @crbonfree/sdk/schemas, and validateResponse checks a payload against them before your code sees it.
Pagination helpers included
Receipts and audit packs arrive in pages. parsePage normalises one page into items with a hasNextPage flag, autoPaginate streams every item as an async iterator, and listAll collects them into a single array. The other ten operations return everything in one call.
How the TypeScript SDK moves your data
- 1
Your code calls a method
One typed call, for example usage.getSummary with a range, with the request shape checked before it leaves.
- 2
The SDK signs it
The API key comes from CRBONFREE_API_KEY or the credentials file that login wrote, and travels as an X-API-Key header.
- 3
The API answers from computed data
Usage, emissions with bounds, receipts and audit packs the backend has already produced. Nothing is metered on this path.
- 4
Your report shows the same figures
Whatever you build, a dashboard, a monthly export or an alert, matches what the CrbonFree dashboard shows for the same range.
How to get started
- 1
Install
Node 18 or newer. The package is MIT licensed and ships as ES modules with type declarations.
npm install @crbonfree/sdk
- 2
Sign in
Opens the browser, signs you in or creates an account, generates an API key and saves it to ~/.crbonfree/credentials. Run whoami to see which account is saved and logout to remove it.
npx @crbonfree/sdk login
- 3
Read a summary
The constructor finds the saved key on its own. Every method returns a promise of the typed response, and its data field carries the same numbers the dashboard shows.
import { CrbonFreeClient } from '@crbonfree/sdk'; const crbon = new CrbonFreeClient(); const { data } = await crbon.usage.getSummary({ range: '30d' }); console.log(data.totals.carbonKg, 'kg CO2e');Prints the last 30 days of CO2e in kilograms.
The same numbers as your dashboard
The SDK reads the twelve public API operations, and what they return is what the backend has already computed for your organisation, so a figure you print from code is the figure on screen. That makes it the right tool for a monthly report, an internal dashboard or an automation that watches the retirement status of the current period. The sample account shows the shapes before you write against them.
Open the sample dashboardWhat it does not do
The SDK is read only. It returns usage, emissions, receipts and audit packs that the backend has already computed, and it has no method for sending usage in, so it cannot meter anything on its own. It authenticates with an API key only; there is no session or bearer-token mode, and because it reads credentials from disk it is built for Node.js rather than the browser. The deprecated cost field on usage totals and per-model breakdowns returns null and will be removed in the next major version. Receipts and audit packs are paid features, so a free plan receives a 402 with an upgrade link.
Who reaches for the TypeScript SDK
Reconciles monthly AI usage against invoices and needs the retirement receipts.
What they get: billing.listReceipts and billing.listAuditPacks page through every retirement with its serial numbers.
Pulls a monthly Scope 3 figure into the group reporting system.
What they get: A scheduled job calls usage.exportDaily and hands the export to the reporting tool.
Which CrbonFree surface do I need?
Three of them put usage in: the dashboard through provider connections, the CLI for coding agents and the browser extension for chat sessions. The other four read the numbers back into your own code. The TypeScript SDK is highlighted.
| Surface | Meters usage | Reads numbers back | Runs | Needs | Language |
|---|---|---|---|---|---|
| Dashboard | In the browser | An account; the sample account opens without one | None | ||
| CLI | status | On your machine | An account; device code for headless machines | Node 20 or newer | |
| Browser extension | estimates | In Chrome | Optional, per the store listing | None | |
| TypeScript SDKthis page | Node 18 or newer | An API key | TypeScript or JavaScript | ||
| Python SDK | Python 3.8 or newer | An API key | Python | ||
| MCP server | Beside your MCP client | An API key from login | Any MCP client | ||
| REST API | Over HTTPS | An API key | Any |
Questions
Questions about the TypeScript SDK.
Short answers. The package page and the API reference have the long ones.
View on npmGenerated from the CrbonFree OpenAPI spec, with Zod schemas alongside the types, so the client follows the API as it changes rather than drifting from it.
No. Every method reads. Usage reaches CrbonFree through a provider connection, the CLI or the browser extension, and the SDK reads back what the backend computed from it.
With an API key only, sent as the X-API-Key header on every request. Running npx @crbonfree/sdk login opens the browser, generates a key that starts with ck_live_ and writes it to ~/.crbonfree/credentials with owner-only permissions. The Python SDK and the MCP server read the same file. In CI, set CRBONFREE_API_KEY or pass apiKey to the constructor; an explicit key wins over the file.
Only billing.listReceipts and billing.listAuditPacks paginate, with page and limit parameters and a pagination block in the response. The package exports parsePage to normalise one page, autoPaginate to stream every item as an async iterator, and listAll to collect everything into an array. The other ten operations return in a single call.
It returns what the backend has already computed for your organisation: token totals and cost, CO2e in kilograms with upper and lower bounds, electricity in kilowatt hours, per-model and per-day breakdowns, the retirement status of the current billing period, signed receipts with their serial allocations and verification URLs, and monthly audit packs. It meters nothing and has no method for sending usage in. Metering happens elsewhere in the platform; this package only reads the results.
Goes well with
All productsDashboardEvery provider, project and coding agent in one report. The sample account opens without a login.CLIMeter your local AI coding agents automatically, synced to the dashboard every hour.Browser extensionEstimates token usage in your AI chat sessions across ChatGPT, Gemini and the Claude apps, including Claude Code. Guest mode keeps everything on your machine, and signing in keeps the history.
See your own number instead of ours.
However your team already runs AI, that is how you connect. Paste a read-only provider key, drop in an SDK, add the MCP server, install the CLI or switch on the browser extension, and the first measured tokens reach your dashboard within seconds.
Create your free account
Free plan · first tokens in seconds