Types

TypeScript types exported by @mdk/core (UI primitives) and @mdk/foundation (mining domain models)

This page documents the TypeScript types exported by the MDK packages. The two packages cover different territory:

@mdk/core ships UI primitive types: sizes, variants, colors, status, common API and chart shapes. These are the building blocks consumed by core components and re-used in your own component prop types.
@mdk/foundation ships mining-domain models: Device, Container, Alert, MinerStats, settings shapes. These describe the data flowing through foundation components and the API responses they consume.

`@mdk/core` types

Prerequisites

Complete the @mdk/core installation and add the dependency

Import

@mdk/core

import type {
  ComponentSize,
  ButtonVariant,
  ColorVariant,
  Status,
  ApiResponse,
} from '@mdk/core'

Common types

`ComponentSize`

@mdk/core

Standard size variants used across multiple components.

type ComponentSize = 'sm' | 'md' | 'lg'

Used by: Button, Badge, Checkbox, Switch, Radio, Spinner, Indicator, EmptyState, Pagination.

`ButtonSize`

@mdk/core

Extends ComponentSize with an icon-only variant.

type ButtonSize = ComponentSize | 'icon'

`ColorVariant`

@mdk/core

Comprehensive color variants for components.

type ColorVariant =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'

`StatusVariant`

@mdk/core

Status variants for state indication.

type StatusVariant = 'success' | 'processing' | 'error' | 'warning' | 'default' | 'idle'

Used by: badges, notifications, status indicators.

`ComponentColor`

@mdk/core

Color options for form components.

type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error'

Used by: Checkbox, Switch, Radio, Typography.

`Position`

@mdk/core

Position/side options for UI elements.

type Position = 'top' | 'right' | 'bottom' | 'left'

Used by: Tooltip, Popover, chart legends.

`TextAlign`

@mdk/core

Text alignment options.

type TextAlign = 'left' | 'center' | 'right' | 'justify'

`FlexAlign`

@mdk/core

Flex/grid alignment options.

type FlexAlign = 'start' | 'center' | 'end'

Component types

`ButtonVariant`

@mdk/core

Button visual variants.

type ButtonVariant =
  | 'primary'
  | 'secondary'
  | 'danger'
  | 'tertiary'
  | 'link'
  | 'icon'
  | 'outline'
  | 'ghost'

`ButtonIconPosition`

@mdk/core

Where icons appear in buttons.

type ButtonIconPosition = 'left' | 'right'

`NotificationVariant`

@mdk/core

Toast/notification variants.

type NotificationVariant = 'success' | 'error' | 'warning' | 'info'

`BadgeStatus`

@mdk/core

Badge status options.

type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default'

`TypographyColor`

@mdk/core

Typography color options including muted.

type TypographyColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'muted'

Utility types

`UnknownRecord`

@mdk/core

Generic type for objects with unknown structure.

type UnknownRecord = Record<string, unknown>

`Nullable` / `Optional` / `Maybe`

@mdk/core

Null/undefined wrapper types.

type Nullable<T> = T | null
type Optional<T> = T | undefined
type Maybe<T> = T | null | undefined

`Status`

@mdk/core

Async operation status.

type Status = 'idle' | 'loading' | 'success' | 'error'

API types

`PaginationParams`

@mdk/core

Pagination request parameters.

type PaginationParams = {
  limit?: number
  offset?: number
  page?: number
}

`PaginatedResponse`

@mdk/core

Paginated response wrapper.

type PaginatedResponse<T> = {
  data: T[]
  page: number
  total: number
  totalPages: number
}

`ApiResponse`

@mdk/core

API response wrapper.

type ApiResponse<T> = {
  data: T
  message?: string
  status: number
}

`ApiError`

@mdk/core

API error response structure.

type ApiError = {
  error: string
  message: string
  status: number
  data?: {
    message?: string
  }
}

Data table types

@mdk/core

Re-exported from TanStack Table for convenience.

import type {
  DataTableColumnDef,
  DataTableExpandedState,
  DataTablePaginationState,
  DataTableRow,
  DataTableRowSelectionState,
  DataTableSortingState,
} from '@mdk/core'

Value types

`ValueUnit`

@mdk/core

A value paired with a unit, used for display formatting.

type ValueUnit = {
  value: number | string | null
  unit: string
  realValue: number
}

`HashrateUnit` / `CurrencyUnit`

@mdk/core

Specialized value-unit aliases.

type HashrateUnit = ValueUnit
type CurrencyUnit = ValueUnit

`UnitLabel`

@mdk/core

SI-prefix unit labels.

type UnitLabel = 'decimal' | 'k' | 'M' | 'G' | 'T' | 'P'

Time types

`TimeRangeFormatted`

@mdk/core

A formatted time range.

type TimeRangeFormatted = {
  start: string
  end: string
  formatted: string
}

`TimeInterval`

@mdk/core

A time interval with start/end timestamps.

type TimeInterval = {
  start: number
  end: number
}

Chart types

`ChartLegendPosition`

@mdk/core

Chart legend position options.

type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea'

`WeightedAverageResult`

@mdk/core

Result from weighted average calculation.

type WeightedAverageResult = {
  avg: number
  totalWeight: number
  weightedValue: number
}

`ErrorWithTimestamp`

@mdk/core

An error with optional timestamp.

type ErrorWithTimestamp = {
  msg?: string
  message?: string
  timestamp?: number | string
}

Foundation types describe the shape of devices, containers, alerts, and settings data flowing through @mdk/foundation components and API responses. They are organized into three barrels: alerts, device, and settings.types.

Prerequisites

Complete the @mdk/foundation installation and add the dependency

Import

@mdk/foundation

import type {
  Alert,
  Device,
  DeviceLast,
  DeviceInfo,
  ContainerSnap,
  ContainerStats,
  MinerStats,
  MinerConfig,
  SettingsUser,
  PermLevel,
} from '@mdk/foundation'

Alert types

`Alert`

@mdk/foundation

Raw alert record as it appears on a device's alerts array.

type Alert = {
  id?: string
  severity: string
  createdAt: number | string
  name: string
  description: string
  message?: string
  uuid?: string
  code?: string | number
  [key: string]: unknown
}

The severity field uses string values like critical, high, medium, low. The open [key: string]: unknown index signature allows vendor-specific fields without breaking the type contract.

`LogFormattedAlertData`

@mdk/foundation

Alert reshaped for log display components (e.g., AlertsLog).

type LogFormattedAlertData = {
  title: string
  subtitle: string
  status: string
  severityLevel: number
  creationDate: number | string
  body: string
  id: string
  uuid?: string
  [key: string]: unknown
}

Device types

The Device family models everything that appears on the device explorer: miners, containers, power meters, temperature sensors, and cabinets. The shape is intentionally permissive (open index signatures, optional fields) because devices come from a live API that adds vendor-specific fields over time.

`Device`

@mdk/foundation

The root device record. Used pervasively in the Operations centre components.

type Device = {
  id: string
  type: string
  tags?: string[]
  rack?: string
  last?: DeviceLast
  username?: string
  info?: DeviceInfo
  containerId?: string
  address?: string | null
  code?: string
  alerts?: Alert[] | null
  powerMeters?: Device[]
  tempSensors?: Device[]
  transformerTempSensor?: Device
  rootTempSensor?: Device
  [key: string]: unknown
}

The type string discriminates devices by category (such as miner or container) and by vendor. The last field carries the latest snapshot from the device.

`DeviceLast`

@mdk/foundation

The latest reading wrapper that lives on Device.last.

type DeviceLast = {
  err?: string | null
  type?: string
  snap?: ContainerSnap
  alerts?: Alert[] | null
  [key: string]: unknown
}

err is a connection or upstream error string when the device is unreachable. snap carries the actual stats and config payload.

`DeviceInfo`

@mdk/foundation

Identification and placement metadata that lives on Device.info.

type DeviceInfo = {
  container?: string
  pos?: string
  poolConfig?: string
  serialNum?: string
  macAddress?: string | null
  posHistory?: Partial<PosHistoryEntry[]>
  [key: string]: unknown
}

`PosHistoryEntry`

@mdk/foundation

A single past placement of a miner.

type PosHistoryEntry = {
  container: string
  pos: string
  removedAt: number
}

`DeviceData`

@mdk/foundation

A flattened version of Device with a guaranteed (non-optional) snap field, returned by the getDeviceData helper.

type DeviceData = {
  id: string
  type: string
  tags?: string[]
  rack?: string
  snap: ContainerSnap
  alerts?: Alert[]
  username?: string
  info?: DeviceInfo
  containerId?: string
  address?: string
  err?: string
  [key: string]: unknown
}

Container types

`Container`

@mdk/foundation

A Device specialized for containers, with container-specific info and last shapes.

type Container = {
  info?: Partial<ContainerInfo>
  last?: Partial<ContainerLast>
} & Device

`ContainerInfo`

@mdk/foundation

Cooling, supply, and pressure metadata for a container.

type ContainerInfo = {
  container: string
  cooling_system: Record<string, unknown>
  cdu: Record<string, unknown>
  primary_supply_temp: number
  second_supply_temp1: number
  second_supply_temp2: number
  supply_liquid_temp: number
  supply_liquid_set_temp: number
  supply_liquid_pressure: number
  return_liquid_pressure: number
}

`ContainerPosInfo`

@mdk/foundation

Position descriptor for a device inside a container (PDU/socket coordinates).

type ContainerPosInfo = {
  containerInfo: Partial<{ container: string; type: string }>
  pdu: string | number
  socket: string | number
  pos: string
  [key: string]: unknown
}

`ContainerLast`

@mdk/foundation

Last-snapshot wrapper for a container.

type ContainerLast = {
  snap: {
    stats?: Partial<ContainerStats>
  }
  alerts: unknown[] | null
  err: string | null
}

`ContainerSnap`

@mdk/foundation

The snap payload found on DeviceLast.snap for both miners and containers. stats is what most components read.

type ContainerSnap = {
  stats?: Partial<ContainerStats>
  config?: Record<string, unknown>
}

`ContainerStats`

@mdk/foundation

The big stats blob produced by every container snapshot.

type ContainerStats = {
  status: string
  ambient_temp_c: number
  humidity_percent: number
  power_w: number
  container_specific: Partial<ContainerSpecific>
  distribution_box1_power_w: number
  distribution_box2_power_w: number
  stats: Record<string, unknown>
  temperature_c: Partial<StatsTemperatureC>
  frequency_mhz: Partial<StatsFrequencyMhz>
  miner_specific: Partial<MinerSpecificStats>
  [key: string]: unknown
}

status is one of running, offline, stopped (see CONTAINER_STATUS in Constants).

`ContainerSpecific`

@mdk/foundation

Container-specific stats (currently the PDU array).

type ContainerSpecific = {
  pdu_data: Partial<ContainerPduData>[]
  [key: string]: unknown
}

`ContainerPduData`

@mdk/foundation

Per-PDU power and status reading.

type ContainerPduData = {
  power_w: number
  status: number
}

`StatsTemperatureC`

@mdk/foundation

Temperature stats with per-chip detail.

type StatsTemperatureC = {
  avg: number
  min: number
  max: number
  chips: TempChipData[]
  [key: string]: unknown
}

`StatsFrequencyMhz`

@mdk/foundation

Frequency stats with per-chip detail.

type StatsFrequencyMhz = {
  avg: number
  chips: ChipData[]
  [key: string]: unknown
}

`ChipData` / `TempChipData`

@mdk/foundation

Per-chip readings.

type ChipData = {
  index: number
  current: number
}

type TempChipData = {
  index: number
  max?: number
  min?: number
  avg?: number
}

`MinerSpecificStats`

@mdk/foundation

Miner-specific stats blob.

type MinerSpecificStats = {
  upfreq_speed: number
  [key: string]: unknown
}

Miner types

`MinerStats`

@mdk/foundation

Per-miner stats reported on each snapshot.

type MinerStats = {
  status?: string
  uptime_ms?: number
  power_w?: number
  hashrate_mhs?: MinerHashrateMhs
  poolHashrate?: string
  temperature_c?: { max?: number }
}

`MinerHashrateMhs`

@mdk/foundation

Hashrate readings, currently just the rolling 5-minute window.

type MinerHashrateMhs = {
  t_5m?: number
}

`MinerInfo`

@mdk/foundation

Identifying info for a miner (used by miner record cards).

type MinerInfo = {
  container?: string
  pos?: string
  macAddress?: string
  serialNum?: string
}

`MinerConfig`

@mdk/foundation

Mutable miner configuration.

type MinerConfig = {
  firmware_ver?: string
  power_mode?: string
  led_status?: boolean
}

power_mode values come from MINER_POWER_MODE (sleep, low, normal, high).

`MinerDeviceSnapshot`

@mdk/foundation

Lightweight snapshot wrapper holding only MinerConfig.

type MinerDeviceSnapshot = {
  last?: { snap?: { config?: MinerConfig } }
}

`MinerRecord`

@mdk/foundation

Combined miner record used by list/table views.

type MinerRecord = {
  id?: string
  shortCode?: string
  info?: MinerInfo
  address?: string
  type?: string
  alerts?: unknown[]
  stats?: MinerStats
  config?: MinerConfig
  device?: MinerDeviceSnapshot
  error?: string
  err?: string
  isPoolStatsEnabled?: boolean
}

Power and cabinet types

`PowerMeter`

@mdk/foundation

Minimal power meter reading shape.

type PowerMeter = {
  last?: {
    snap?: {
      stats?: {
        power_w?: number
      }
    }
  }
}

`LvCabinetRecord`

@mdk/foundation

LV cabinet record carrying its associated power meters.

type LvCabinetRecord = {
  id: string
  powerMeters?: PowerMeter[]
}

Settings types

`SettingsUser`

@mdk/foundation

A user record as it appears in user-management lists.

type SettingsUser = {
  id: string
  name?: string
  email: string
  role: string
  last_login?: string
  lastActive?: string
  [key: string]: unknown
}

`RoleOption`

@mdk/foundation

Role option for select dropdowns. Also exported as the array USER_ROLES in Constants.

type RoleOption = {
  label: string
  value: string
}

`PermLevel`

@mdk/foundation

Permission level values.

type PermLevel = 'rw' | 'r' | false

`RolesPermissionsData`

@mdk/foundation

The shape consumed by RBACControlSettings.

type RolesPermissionsData = {
  permissions: Record<string, Record<string, PermLevel>>
  labels: Record<string, string>
}

`SettingsExportData`

@mdk/foundation

The export envelope produced and consumed by ImportExportSettings. Generic TExtra lets you attach app-specific extras.

type SettingsExportData<TExtra extends Record<string, unknown> = Record<string, unknown>> = {
  headerControls?: Record<string, boolean>
  featureFlags?: Record<string, boolean>
  timestamp?: string
  version?: string
} & TExtra

`ImportResult`

@mdk/foundation

Result returned from settings import operations.

type ImportResult = {
  success: boolean
  applied?: string[]
  errors?: string[]
  message?: string
}

On this page