@adminforth/dashboard 1.1.0 → 1.2.0

package/README.md

@@ -30,19 +30,18 @@ Each widget has common fields:
 | `target` | Widget type: `table`, `chart`, `kpi_card`, `pivot_table`, or `gauge_card`. |
 | `order` | Widget order inside its group. |
 | `size` | Preset width: `small`, `medium`, `large`, `wide`, or `full`. |
-| `width`, `height`, `minWidth`, `maxWidth` | Optional explicit layout constraints. |
-| `dataSource` | Optional resource or aggregate data source definition. |
-| `query` | Optional AdminForth resource query used to load widget data. |
+| `width`, `height`, `min_width`, `max_width` | Optional explicit layout constraints. |
+| `data_source` | Resource or aggregate data source definition. |
 
 ## Widget Support Matrix
 
 | Widget target | Config field | Main settings | Data usage |
 | --- | --- | --- | --- |
-| `table` | `table` | `columns`, `pagination`, `pageSize` | Uses `dataSource.type = 'resource'` or legacy `query` to display resource rows with backend pagination unless `pagination` is `false`. |
-| `chart` | `chart` | `type`, `x_field`, `y_field`, `label_field`, `value_field`, `bucket_field`, `buckets`, `series`, `series_name`, `color`, `colors` | Supports legacy `query` or `dataSource.type = 'aggregate'` with `groupBy`. |
-| `kpi_card` | `kpi_card` | `value_field`, `label_field`, `prefix`, `suffix` | Reads the first row or aggregate values and formats one numeric value. |
-| `gauge_card` | `gauge_card` | `value_field`, `min`, `max`, `min_field`, `max_field`, `suffix`, `color` | Reads the first row or aggregate values and renders progress between static or field-driven bounds. |
-| `pivot_table` | `pivot_table` | `row_field`, `column_field`, `value_field`, `aggregation` | Supports legacy row-based queries and grouped aggregate rows. `aggregation` supports `count` and `sum`. |
+| `table` | `table` | `pagination`, `page_size` | Uses `data_source.type = 'resource'` to display resource rows with backend pagination unless `pagination` is `false`. |
+| `chart` | `chart` | `type`, `x_field`, `y_field`, `label_field`, `value_field`, `bucket_field`, `buckets`, `series`, `series_name`, `color`, `colors` | Uses `data_source.type = 'aggregate'` with `group_by`. |
+| `kpi_card` | `kpi_card` | `value_field`, `label_field`, `prefix`, `suffix` | Reads aggregate values or the first returned row from `data_source`. |
+| `gauge_card` | `gauge_card` | `value_field`, `min`, `max`, `min_field`, `max_field`, `suffix`, `color` | Reads aggregate values or the first returned row from `data_source` and renders progress between static or field-driven bounds. |
+| `pivot_table` | `pivot_table` | `row_field`, `column_field`, `value_field`, `aggregation` | Uses grouped aggregate rows from `data_source.type = 'aggregate'`. `aggregation` supports `count` and `sum`. |
 
 Chart widget types:
 
@@ -55,41 +54,25 @@ Chart widget types:
 | `funnel` | Uses `label_field`, `value_field`, and optional `colors`. |
 | `histogram` | Uses the same bucket settings as `bar`. |
 
-## Query Shape
-
-```ts
-type DashboardWidgetQuery = {
-  resource: string
-  select?: string[]
-  order?: {
-    field: string
-    direction: 'asc' | 'desc'
-  }
-  limit?: number
-}
-```
-
-`resource` is an AdminForth `resourceId`. The query is executed through AdminForth resources, so widgets use the same resource contracts as the rest of the application.
-
 ## Data Source Shape
 
 ```ts
 type WidgetDataSource =
   | {
       type: 'resource'
-      resourceId: string
+      resource_id: string
       columns?: string[]
       filters?: unknown
       sort?: unknown
     }
   | {
       type: 'aggregate'
-      resourceId: string
+      resource_id: string
       aggregations: Record<string, {
         operation: 'sum' | 'count' | 'avg' | 'min' | 'max' | 'median'
         field?: string
       }>
-      groupBy?:
+      group_by?:
         | { type: 'field'; field: string }
         | {
             type: 'date_trunc'
@@ -101,7 +84,7 @@ type WidgetDataSource =
     }
 ```
 
-`query` remains supported for backwards compatibility. When both are present, widgets prefer `dataSource`.
+  `resource_id` is an AdminForth `resourceId`. The data source is executed through AdminForth resources, so widgets use the same resource contracts as the rest of the application.
 
 ## Runtime Structure
 

package/custom/model/dashboard.types.ts

@@ -88,7 +88,6 @@ export type DashboardWidgetConfig = {
   kpi_card?: unknown
   pivot_table?: unknown
   gauge_card?: unknown
-  query?: unknown
 }
 
 export type DashboardWidgetTableData = {
@@ -112,6 +111,30 @@ export type DashboardWidgetAggregateData = {
 
 export type DashboardWidgetData = DashboardWidgetTableData | DashboardWidgetAggregateData
 
+export type NormalizedKpiCardWidgetConfig = {
+  valueField?: string
+  labelField?: string
+  prefix?: string
+  suffix?: string
+}
+
+export type NormalizedGaugeCardWidgetConfig = {
+  valueField?: string
+  min?: number | string
+  max?: number | string
+  minField?: string
+  maxField?: string
+  suffix?: string
+  color?: string
+}
+
+export type NormalizedPivotTableWidgetConfig = {
+  rowField?: string
+  columnField?: string
+  valueField?: string
+  aggregation?: 'count' | 'sum'
+}
+
 export function normalizeDashboardConfig(config: unknown): DashboardConfig {
   const value = isRecord(config) ? config : {}
 
@@ -130,29 +153,114 @@ export function normalizeDashboardWidgetConfig(config: unknown) {
   }
 
   const normalized: Record<string, unknown> = { ...config }
-  const target = normalizeDashboardWidgetTarget(normalized.target ?? normalized.type)
+  normalizeWidgetLayoutConfig(normalized)
+
+  if (normalized.table !== undefined) {
+    normalized.table = normalizeTableConfig(normalized.table)
+  }
+
+  if (normalized.data_source !== undefined) {
+    normalized.dataSource = normalizeWidgetDataSource(normalized.data_source)
+  }
 
-  if (target && normalized.target === undefined) {
+  const target = normalizeDashboardWidgetTarget(normalized.target)
+
+  if (target !== undefined) {
     normalized.target = target
   }
 
-  if (target === 'kpi_card') {
-    const kpiCardConfig = normalizeKpiCardConfig(normalized)
+  return normalized
+}
 
-    if (kpiCardConfig !== undefined) {
-      normalized.kpi_card = kpiCardConfig
-    }
+export function serializeDashboardWidgetConfigForEditor(widget: DashboardWidgetConfig) {
+  const serialized: Record<string, unknown> = { ...widget }
+
+  if (Object.prototype.hasOwnProperty.call(serialized, 'minWidth')) {
+    serialized.min_width = widget.minWidth
+    delete serialized.minWidth
   }
 
-  if (target === 'gauge_card') {
-    const gaugeCardConfig = normalizeGaugeCardConfig(normalized)
+  if (Object.prototype.hasOwnProperty.call(serialized, 'maxWidth')) {
+    serialized.max_width = widget.maxWidth
+    delete serialized.maxWidth
+  }
 
-    if (gaugeCardConfig !== undefined) {
-      normalized.gauge_card = gaugeCardConfig
-    }
+  if (widget.table !== undefined) {
+    serialized.table = serializeTableConfigForEditor(widget.table)
   }
 
-  return normalized
+  if (widget.dataSource !== undefined) {
+    serialized.data_source = serializeWidgetDataSourceForEditor(widget.dataSource)
+    delete serialized.dataSource
+  }
+
+  return serialized
+}
+
+export function normalizeKpiCardWidgetConfig(value: unknown): NormalizedKpiCardWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const valueField = getStringField(config, 'value_field')
+  const labelField = getStringField(config, 'label_field')
+  const prefix = getStringField(config, 'prefix')
+  const suffix = getStringField(config, 'suffix')
+
+  return {
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(labelField !== undefined ? { labelField } : {}),
+    ...(prefix !== undefined ? { prefix } : {}),
+    ...(suffix !== undefined ? { suffix } : {}),
+  }
+}
+
+export function normalizeGaugeCardWidgetConfig(value: unknown): NormalizedGaugeCardWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const valueField = getStringField(config, 'value_field')
+  const minField = getStringField(config, 'min_field')
+  const maxField = getStringField(config, 'max_field')
+  const suffix = getStringField(config, 'suffix')
+  const color = getStringField(config, 'color')
+
+  return {
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(config.min !== undefined ? { min: config.min as number | string } : {}),
+    ...(config.max !== undefined ? { max: config.max as number | string } : {}),
+    ...(minField !== undefined ? { minField } : {}),
+    ...(maxField !== undefined ? { maxField } : {}),
+    ...(suffix !== undefined ? { suffix } : {}),
+    ...(color !== undefined ? { color } : {}),
+  }
+}
+
+export function normalizePivotTableWidgetConfig(value: unknown): NormalizedPivotTableWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const rowField = getStringField(config, 'row_field')
+  const columnField = getStringField(config, 'column_field')
+  const valueField = getStringField(config, 'value_field')
+  const aggregation = config.aggregation === 'count' || config.aggregation === 'sum'
+    ? config.aggregation
+    : undefined
+
+  return {
+    ...(rowField !== undefined ? { rowField } : {}),
+    ...(columnField !== undefined ? { columnField } : {}),
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(aggregation !== undefined ? { aggregation } : {}),
+  }
 }
 
 function normalizeDashboardWidgetTarget(value: unknown): DashboardWidgetTarget | undefined {
@@ -169,60 +277,146 @@ function normalizeDashboardWidgetTarget(value: unknown): DashboardWidgetTarget |
   }
 }
 
-function normalizeKpiCardConfig(value: Record<string, unknown>) {
-  const config = isRecord(value.kpi_card) ? { ...value.kpi_card } : {}
+function normalizeWidgetLayoutConfig(value: Record<string, unknown>) {
+  if (value.min_width !== undefined) {
+    value.minWidth = value.min_width
+  }
 
-  if (typeof value.valueField === 'string' && config.value_field === undefined) {
-    config.value_field = value.valueField
+  if (value.max_width !== undefined) {
+    value.maxWidth = value.max_width
   }
+}
 
-  if (typeof value.labelField === 'string' && config.label_field === undefined) {
-    config.label_field = value.labelField
+function normalizeTableConfig(value: unknown) {
+  if (!isRecord(value)) {
+    return value
   }
 
-  if (typeof value.prefix === 'string' && config.prefix === undefined) {
-    config.prefix = value.prefix
+  const normalized = { ...value }
+
+  if (normalized.page_size !== undefined) {
+    normalized.pageSize = normalized.page_size
   }
 
-  if (typeof value.suffix === 'string' && config.suffix === undefined) {
-    config.suffix = value.suffix
+  return normalized
+}
+
+function normalizeWidgetDataSource(value: unknown) {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return value
+  }
+
+  const resourceId = typeof value.resource_id === 'string'
+    ? value.resource_id
+    : undefined
+
+  if (value.type === 'resource') {
+    return {
+      type: 'resource',
+      ...(resourceId !== undefined ? { resourceId } : {}),
+      ...(value.columns !== undefined ? { columns: value.columns } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+      ...(value.sort !== undefined ? { sort: value.sort } : {}),
+    }
+  }
+
+  if (value.type === 'aggregate') {
+    const groupBy = normalizeGroupByRule(value.group_by)
+
+    return {
+      type: 'aggregate',
+      ...(resourceId !== undefined ? { resourceId } : {}),
+      ...(value.aggregations !== undefined ? { aggregations: value.aggregations } : {}),
+      ...(groupBy !== undefined ? { groupBy } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+    }
   }
 
-  return Object.keys(config).length ? config : value.kpi_card
+  return value
 }
 
-function normalizeGaugeCardConfig(value: Record<string, unknown>) {
-  const config = isRecord(value.gauge_card) ? { ...value.gauge_card } : {}
+function normalizeGroupByRule(value: unknown) {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return value
+  }
 
-  if (typeof value.valueField === 'string' && config.value_field === undefined) {
-    config.value_field = value.valueField
+  if (value.type === 'field') {
+    return {
+      type: 'field',
+      ...(value.field !== undefined ? { field: value.field } : {}),
+    }
   }
 
-  if (value.min !== undefined && config.min === undefined) {
-    config.min = value.min
+  if (value.type === 'date_trunc') {
+    return {
+      type: 'date_trunc',
+      ...(value.field !== undefined ? { field: value.field } : {}),
+      ...(value.truncation !== undefined ? { truncation: value.truncation } : {}),
+      ...(value.timezone !== undefined ? { timezone: value.timezone } : {}),
+    }
   }
 
-  if (value.max !== undefined && config.max === undefined) {
-    config.max = value.max
+  return value
+}
+
+function serializeTableConfigForEditor(value: unknown) {
+  if (!isRecord(value)) {
+    return value
   }
 
-  if (typeof value.minField === 'string' && config.min_field === undefined) {
-    config.min_field = value.minField
+  const serialized = { ...value }
+
+  if (Object.prototype.hasOwnProperty.call(serialized, 'pageSize')) {
+    serialized.page_size = serialized.pageSize
+    delete serialized.pageSize
+  }
+
+  return serialized
+}
+
+function serializeWidgetDataSourceForEditor(value: WidgetDataSource) {
+  if (value.type === 'resource') {
+    return {
+      type: 'resource',
+      resource_id: value.resourceId,
+      ...(value.columns !== undefined ? { columns: value.columns } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+      ...(value.sort !== undefined ? { sort: value.sort } : {}),
+    }
   }
 
-  if (typeof value.maxField === 'string' && config.max_field === undefined) {
-    config.max_field = value.maxField
+  return {
+    type: 'aggregate',
+    resource_id: value.resourceId,
+    aggregations: value.aggregations,
+    ...(value.groupBy !== undefined ? { group_by: serializeGroupByRuleForEditor(value.groupBy) } : {}),
+    ...(value.filters !== undefined ? { filters: value.filters } : {}),
   }
+}
 
-  if (typeof value.suffix === 'string' && config.suffix === undefined) {
-    config.suffix = value.suffix
+function serializeGroupByRuleForEditor(value: GroupByRule) {
+  if (value.type === 'field') {
+    return {
+      type: 'field',
+      field: value.field,
+    }
   }
 
-  if (typeof value.color === 'string' && config.color === undefined) {
-    config.color = value.color
+  return {
+    type: 'date_trunc',
+    field: value.field,
+    truncation: value.truncation,
+    ...(value.timezone !== undefined ? { timezone: value.timezone } : {}),
   }
+}
+
+function asWidgetConfigRecord(value: unknown): Record<string, unknown> | undefined {
+  return isRecord(value) ? value : undefined
+}
 
-  return Object.keys(config).length ? config : value.gauge_card
+function getStringField(record: Record<string, unknown>, key: string) {
+  const value = record[key]
+  return typeof value === 'string' ? value : undefined
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/custom/runtime/DashboardRuntime.vue

@@ -211,6 +211,7 @@ import type {
   DashboardWidgetConfig,
   DashboardWidgetMoveDirection,
 } from '../model/dashboard.types.js'
+import { serializeDashboardWidgetConfigForEditor } from '../model/dashboard.types.js'
 
 const props = defineProps<{
   dashboardSlug: string
@@ -388,7 +389,7 @@ async function removeWidget(widgetId: string) {
 
 function editWidget(widget: DashboardWidgetConfig) {
   editingWidgetId.value = widget.id
-  widgetConfigCode.value = stringifyYaml(widget)
+  widgetConfigCode.value = stringifyYaml(serializeDashboardWidgetConfigForEditor(widget))
   widgetConfigError.value = ''
   widgetConfigFieldErrors.value = []
 }

package/custom/runtime/WidgetRenderer.vue

@@ -26,6 +26,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import type { DashboardWidgetConfig } from '../model/dashboard.types.js'
+import { normalizeChartWidgetConfig } from '../widgets/chart/chart.types.js'
 import { getWidgetLabel, getWidgetRegistration } from '../widgets/registry.js'
 
 const props = defineProps<{
@@ -52,7 +53,7 @@ const widgetTitle = computed(() => {
   }
 
   if (props.widget.target === 'chart') {
-    return props.widget.chart?.title || 'Untitled chart'
+    return normalizeChartWidgetConfig(props.widget.chart)?.title || 'Untitled chart'
   }
 
   return getWidgetLabel(props.widget.target)

package/custom/skills/adminforth-dashboard/SKILL.md

@@ -119,7 +119,7 @@ Use the current schema keys exactly:
 
 - Use `target`, not `type`.
 - Use `label`, not `title`.
-- Use `query.resource`, not `resourceId`.
-- Use `query.select`, not `columns`.
-- Use `query.order`, not `sort`.
-- Use `query.limit` for row count.
+- Use `data_source`, not `dataSource`.
+- Use `resource_id`, not `resourceId`.
+- Use `group_by`, not `groupBy`.
+- Use `page_size`, not `pageSize`.

package/custom/widgets/chart/ChartWidget.vue

@@ -26,7 +26,7 @@
       :rows="rows"
       :x-field="xField"
       :y-field="yField"
-      :series-name="chartConfig.series_name"
+      :series-name="chartConfig.seriesName"
       :color="chartConfig.color"
       :height="chartHeight"
     />
@@ -91,6 +91,7 @@
 import { computed, watch } from 'vue'
 import { useWidgetData } from '../../queries/useWidgetData.js'
 import type { DashboardWidgetConfig, DashboardWidgetTableData } from '../../model/dashboard.types.js'
+import { normalizeChartWidgetConfig } from './chart.types.js'
 import BarChart from './bar/BarChart.vue'
 import FunnelChart from './funnel/FunnelChart.vue'
 import HistogramChart from './histogram/HistogramChart.vue'
@@ -126,13 +127,45 @@ watch(
 const chartData = computed(() => data.value?.data as DashboardWidgetTableData | null)
 const rows = computed(() => chartData.value?.rows ?? [])
 const columns = computed(() => chartData.value?.columns ?? [])
-const chartConfig = computed(() => props.widget.chart)
-const xField = computed(() => chartConfig.value?.x_field || columns.value[0])
-const yField = computed(() => chartConfig.value?.y_field || columns.value[1])
-const labelField = computed(() => chartConfig.value?.label_field || columns.value[0])
-const valueField = computed(() => chartConfig.value?.value_field || columns.value[1])
+const chartConfig = computed(() => normalizeChartWidgetConfig(props.widget.chart))
+const aggregateGroupField = computed(() => {
+  const dataSource = props.widget.dataSource
+
+  if (dataSource?.type !== 'aggregate' || !dataSource.groupBy) {
+    return undefined
+  }
+
+  return dataSource.groupBy.field
+})
+
+function resolveChartDimensionField(field: string | undefined, fallbackField: string | undefined) {
+  const resolvedField = field ?? fallbackField
+
+  if (!resolvedField) {
+    return ''
+  }
+
+  if (columns.value.includes(resolvedField)) {
+    return resolvedField
+  }
+
+  if (
+    aggregateGroupField.value
+    && resolvedField === aggregateGroupField.value
+    && columns.value.includes('group')
+  ) {
+    return 'group'
+  }
+
+  return resolvedField
+}
+
+const xField = computed(() => resolveChartDimensionField(chartConfig.value?.xField, columns.value[0]))
+const yField = computed(() => chartConfig.value?.yField || columns.value[1])
+const labelField = computed(() => resolveChartDimensionField(chartConfig.value?.labelField, columns.value[0]))
+const valueField = computed(() => chartConfig.value?.valueField || columns.value[1])
 const pieRows = computed(() => {
-  if (chartConfig.value?.value_field) {
+  if (chartConfig.value?.valueField) {
     return rows.value
   }
 
@@ -147,10 +180,10 @@ const pieRows = computed(() => {
 
   return Array.from(groupedRows.values())
 })
-const pieLabelField = computed(() => chartConfig.value?.value_field ? labelField.value : 'label')
-const pieValueField = computed(() => chartConfig.value?.value_field ? valueField.value : 'value')
+const pieLabelField = computed(() => chartConfig.value?.valueField ? labelField.value : 'label')
+const pieValueField = computed(() => chartConfig.value?.valueField ? valueField.value : 'value')
 const barRows = computed(() => {
-  const bucketField = chartConfig.value?.bucket_field
+  const bucketField = chartConfig.value?.bucketField
 
   if (!bucketField) {
     return rows.value
@@ -167,8 +200,8 @@ const barRows = computed(() => {
     }).length,
   }))
 })
-const barLabelField = computed(() => chartConfig.value?.bucket_field ? 'label' : labelField.value)
-const barValueField = computed(() => chartConfig.value?.bucket_field ? 'count' : valueField.value)
+const barLabelField = computed(() => chartConfig.value?.bucketField ? 'label' : labelField.value)
+const barValueField = computed(() => chartConfig.value?.bucketField ? 'count' : valueField.value)
 const stackedBarSeries = computed(() => {
   if (chartConfig.value?.series?.length) {
     return chartConfig.value.series

package/custom/widgets/chart/chart.types.ts

@@ -32,3 +32,86 @@ export type ChartWidgetConfig = {
   color?: string
   colors?: string[]
 }
+
+export type NormalizedChartWidgetConfig = {
+  type: ChartWidgetType
+  title?: string
+  xField?: string
+  yField?: string
+  labelField?: string
+  valueField?: string
+  bucketField?: string
+  buckets?: ChartWidgetBucketConfig[]
+  series?: ChartWidgetSeriesConfig[]
+  seriesName?: string
+  color?: string
+  colors?: string[]
+}
+
+export function normalizeChartWidgetConfig(value: unknown): NormalizedChartWidgetConfig | undefined {
+  const config = asChartWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const type = normalizeChartWidgetType(config.type)
+
+  if (!type) {
+    return undefined
+  }
+
+  const xField = getStringField(config, 'x_field')
+  const yField = getStringField(config, 'y_field')
+  const labelField = getStringField(config, 'label_field')
+  const valueField = getStringField(config, 'value_field')
+  const bucketField = getStringField(config, 'bucket_field')
+  const seriesName = getStringField(config, 'series_name')
+  const title = getStringField(config, 'title')
+  const color = getStringField(config, 'color')
+  const colors = Array.isArray(config.colors) ? config.colors as string[] : undefined
+  const buckets = Array.isArray(config.buckets) ? config.buckets as ChartWidgetBucketConfig[] : undefined
+  const series = Array.isArray(config.series) ? config.series as ChartWidgetSeriesConfig[] : undefined
+
+  return {
+    type,
+    ...(title !== undefined ? { title } : {}),
+    ...(xField !== undefined ? { xField } : {}),
+    ...(yField !== undefined ? { yField } : {}),
+    ...(labelField !== undefined ? { labelField } : {}),
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(bucketField !== undefined ? { bucketField } : {}),
+    ...(buckets !== undefined ? { buckets } : {}),
+    ...(series !== undefined ? { series } : {}),
+    ...(seriesName !== undefined ? { seriesName } : {}),
+    ...(color !== undefined ? { color } : {}),
+    ...(colors !== undefined ? { colors } : {}),
+  }
+}
+
+function normalizeChartWidgetType(value: unknown): ChartWidgetType | undefined {
+  switch (value) {
+    case 'line':
+    case 'pie':
+    case 'bar':
+    case 'stacked_bar':
+    case 'funnel':
+    case 'histogram':
+      return value
+    default:
+      return undefined
+  }
+}
+
+function asChartWidgetConfigRecord(value: unknown): Record<string, unknown> | undefined {
+  return isRecord(value) ? value : undefined
+}
+
+function getStringField(record: Record<string, unknown>, key: string) {
+  const value = record[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}