Adding a Provider

Every provider follows the same shape, defined by the ProviderAdapter contract in src/collectors/types.ts: a collect(context) function that returns a uniform result — resources, metrics, costs, healthChecks, errors, and a status (success | partial_success | skipped | failed).

Tip

This page is adapted from the repo’s CONTRIBUTING.md.

The dependency-injection seam

Adapters never construct their own network clients — they receive a client interface, and the real implementation lives separately in liveClients/. Tests inject fakes; nothing in providers/ makes a real network call. Keep that split when adding a new provider.

Steps

Use an existing adapter (e.g. src/collectors/providers/cloudflare.ts) as a reference.

1. Extend ProviderKey in src/types.ts with your provider’s key.
2. Add src/collectors/providers/<name>.ts — pure adapter logic. It takes a typed client interface and maps the response into the CollectorAdapterResult shape. No fetch, no SDK client construction, no env var reads here.
3. Add src/collectors/liveClients/<name>.ts — the real implementation of that client interface (actual API/SDK calls, given credentials as plain arguments).
4. Wire it into src/collectors/runConfiguredCollectors.ts behind a credential check — the adapter is only added to the run when its required env vars/config fields are present. This file is the one place that reads env vars and config.
5. Add a label and icon in providerLabels / the icon map in src/App.tsx so the frontend renders your provider nicely.
6. Add a mocked test under src/tests/collectors/providers/<name>.test.ts covering at least success, partial/degraded, and error cases with a fake client — no real network calls in CI.
7. Document credentials in the config table and required-secrets list in docs/SELF_HOSTING.md, and add the env var(s) to .env.example.

Data boundaries

Caution

This tool collects aggregate operational signals only — status, counts, durations, costs. It never stores raw user data, request payloads, message bodies, or table dumps from a watched app. A new adapter must not change that.

See the architecture page for the full data-safety rules.