API Reference · core

Client, chart, table, and filter APIs from @meterry/component for building usage dashboards in any framework.

Auth & client

Export	Description
`SubjectClient`	Subject API client: token injection, expiry refresh, single 401 retry
`createSubjectTokenGetter(endpoint, options?)`	Application-token GET helper, forwarding credentials, fetch and cancellation
`createSubjectTokenProvider(getJwt, options?)`	Creates a reusable token provider (single-flight)
`getSharedSubjectTokenProvider(scope, getJwt, options?)`	Shares a provider per scope (the basis of `tokenScope` compatibility mode)
`clearSharedSubjectToken(scope)`	Clears tokens for a shared scope on logout or account switching
`DEFAULT_SUBJECT_TOKEN_STORAGE_KEY`	Default localStorage key: `meter:subject-token`

SubjectClient methods:

usageQuery(request) — POST /v1/subject/usage/query
analysisQuery(request) — POST /v1/subject/analysis/query
usageDetails(request) — GET /v1/subject/usage/events/details
realtimeBalance(request) — GET /v1/subject/realtime/balance
request<T>(path, init) — any endpoint (reuses the token / 401 logic)
clearToken() — clears the cached token

Automatic usage queries

See Getting Started and the component guides for full types, validation and examples.

Export	Behavior
`createUsageTableController(options)`	Usage aggregate or events cursor query; implements `TableController<UsageTableRow>` plus `dispose()`
`resolveUsageTableColumns(source?, query?, columns?)`	Generated/custom columns; disables unsupported global sorting and event column filters
`serializeUsageTableQuery(query?)`	Stable content-based query identity
`createUsageChartController(options)`	Query, aggregate, cache, subscribe, load/refresh and dispose
`createUsageChartRequest(options, now?)`	Normalize mode, metric/measure, range, grouping and limit
`aggregateUsageTrend(response, normalizedQuery)`	Sum duplicate bucket/series points, preserve metric/non-time dimensions, sort buckets and zero-fill returned bucket union
`aggregateUsageCategories(response, normalizedQuery)`	Group and sum one metric/measure, omit zeros and reject negative totals
`resolveUsageChartMode(type, mode?)`	Resolve trend/category; pie/doughnut force category
`serializeUsageChartQuery(query)`	Content-based chart query key
`clearUsageChartCache(client)`	Clear a client’s result cache; remount/refetch active views on identity changes

Table options default to source: 'usage', rangeDays: 7, pageSize: 20, batchSize: 500, maxCachedRows: 10000. UsageTableQuery omits API limit/cursor; events accept only time and metric selectors. TableState.pagination adds { total: number | null, loadedCount, hasNextPage, hasPreviousPage, truncated }. Legacy state.total is a discovered count; custom cursor footers must inspect pagination.total. The backend’s detail total is not used to drive this wrapper. load() retries the desired page; refresh() starts a new query session; setData/global setSort are unsupported. See automatic table.

Chart options: client, mode: 'trend' | 'category', query (snake_case, no limit), rangeDays: 7, one measure: 'quantity' | 'amount', limit: 500, cacheTimeMs: 30000. UsageChartState has status, result, error; UsageChartResult has mode, measure, data, series, sourceCount, truncated. Result rows contain label, optional raw bucket, and values. Headless consumers must decide whether to suppress truncated results themselves. See automatic chart.

Additional types: UsageTableSource, UsageTableQuery, UsageTableRow, UsageTableOptions, UsageTableController, TablePaginationState, UsageChartMode, UsageChartQuery, UsageChartRow, UsageChartOptions, UsageChartRequest, UsageChartResult, UsageChartState, UsageChartController, and ChartRequestState.

Chart model

Export	Description
`createChartModel(options)`	`ChartOptions<T>` → headless `ChartModel` (labels / series / maxValue / totalValue…)
`renderChartSvg(model, registry?)`	Renders to an SVG string (default width 760)
`registerChartSvgRenderer(type, renderer)`	Registers an SVG renderer, `renderer = (model, width, height) => string`
`unregisterChartSvgRenderer(type)`	Removes an SVG renderer
`createChartSvgRendererRegistry(includeBuiltin?)`	Creates an isolated SVG registry (micro-frontend scenarios)
`getChartSvgRenderer(type, registry?)`	Gets a renderer (unregistered types fall back to built-in behavior)
`formatChartNumber(value)`	Built-in number formatting

ECharts mapping

Export	Description
`createEChartsOption(model, registry?)`	`ChartModel` → ECharts option
`registerEChartsSeries(type, builder, options?)`	Registers a series mapping; `options.modules` loads extra echarts modules, `options.polar` marks polar coordinate systems
`unregisterEChartsSeries(type)`	Removes a registration
`createEChartsSeriesRegistry(includeBuiltin?)`	Creates an isolated ECharts registry
`isPolarChartType(type)`	Whether the type is polar

Use series.format to display readable values such as currency amounts in chart tooltips. See display options and value formatting for an example.

Table controller

const controller = createTableController<T>({ columns, data?, load?, pageSize?, pageSizeOptions? })

TableController<T> methods:

getColumns() / getState() / subscribe(listener) (returns an unsubscribe function)
load() / refresh() / setData(data)
setFilter(key, value) / clearFilters()
setSort(sort: TableSort | null) / setPage(page) / setPageSize(size)

TableState<T>: { status: 'idle' | 'loading' | 'success' | 'error', rows, total, page, pageSize, filters, sort, error }

Helpers: getTableValue(row, accessor, key, index), displayTableValue(value), nextTableSort(key, current), tableSortIndicator(key, current).

Shared filter controller

Export	Description
`createMeterFilterController(definitions, initialValues?)`	Creates page-level shared filter state; explicit initial blanks clear defaults
`normalizeMeterFilters(values)`	Copies a record and drops empty strings; accepts `undefined`; does not whitelist keys
`mergeMeterFilters(...sources)`	Combines records in order; later values win, explicit blanks remove earlier keys, `undefined` sources are skipped

type MeterFilterType = 'text' | 'select' | 'number'
type MeterFilterValues = Record<string, string>
type MeterFilterDefinition = {
  key: string
  label?: string                     // defaults to key
  type?: MeterFilterType             // defaults to a text/search input
  placeholder?: string
  options?: Array<{ label: string; value: string }>
  defaultValue?: string              // applied only at controller creation
}

MeterFilterController methods:

Method	Behavior
`getDefinitions()`	Returns copied definitions and options
`getValues()`	Returns a defensive copy of active values
`subscribe(listener)`	Observes subsequent value changes; returns an unsubscribe function; does not emit immediately
`setValue(key, value)`	Sets one string value; `''` removes it
`setValues(values)`	Replaces all values, dropping empty strings
`clear()`	Clears active values, not restores defaults

Changes are synchronous, and unchanged records do not notify listeners. Use controller methods rather than mutating subscription snapshots. Definitions do not whitelist value keys, and input types do not define matching operators. See Shared Filters for React/Vue bindings and data-component integration.

Styles & copy

Export	Description
`meterClass(slot, classNames?, unstyled?)`	Computes the final class for a single slot
`defaultMeterClasses`	Default `meter-*` classes for all slots
`meterComponentSlots`	Constant listing all slot names
`resolveMeterMessages(messages?)`	Merges default copy
`defaultMeterMessages`	Default English copy
`lightTheme` / `darkTheme`	Built-in themes
`resolveTheme(input)`	`MeterThemeInput` → complete `MeterTheme`
`themeCssVariables(theme, prefix?)`	Generates `--meter-*` CSS variable text
`themeStyles(theme)`	Generates a `<style>` tag string

Usage utilities

Export	Description
`createUsageRequest(query?, rangeDays?, now?)`	`UsageWidgetQuery` → `AnalysisQueryRequest`; normalizes dimension filters and omits an empty `filters` record
`defaultUsageQuery`	Default query constant
`getUsageSummary(response, measure?)`	Totals a given measure
`getUsageChartRows(response, measure?)`	Extracts `{ bucket, value }[]` for a given measure
`formatUsageNumber(value)`	Compact number formatting

Errors

MeterApiError: carries status / statusText / body
isUnauthorizedError(error): whether it was a 401

Type exports also include the full type surface (export type *): ChartOptions, ChartModel, ChartSeries, ChartType, EChartsSeriesBuilder, EChartsSeriesRegistry, TableColumn, TableController, TableOptions, TableQuery, TableSort, TableState, MeterFilterType, MeterFilterDefinition, MeterFilterValues, MeterFilterController, MeterClassNames, MeterMessages, MeterTheme, SubjectTokenGrant, GetJwt, MeterClientOptions, and more.

Load-more list controllers

createListController<T>({ data?, load?, pageSize? }): append local or remote pages, exact loader totals, cancellation and idempotent load/retry.
createUsageListController({ client?, source?, query?, rangeDays?, pageSize?, batchSize? }): automatic usage/event list with cursor buffering; source defaults to events.
resolveUsageListColumns(source?, query?, columns?): default/custom TableColumn<UsageListRow>[].

ListLoad<T> receives ListQuery (table page query plus signal) and returns { rows: T[], total: number }. Return exactly the requested page, not the full collection. Rendering uses the same TableColumn<T> as Table. ListState<T> contains status, appended rows, page, pageSize, total: number | null, hasMore, truncated, error. ListController<T> methods: getState, subscribe, load, loadMore, refresh, setData, dispose. UsageListController uses the same methods; setData is unsupported for query-owned lists. Also exported: ListOptions, UsageListOptions, UsageListRow, MeterListFooterSlotContext. Cells reuse MeterTableCellSlotContext. See List behavior and limits.