@adminforth/dashboard 1.9.0 → 1.11.0

package/custom/api/dashboardApi.ts

@@ -25,6 +25,13 @@ export type DashboardWidgetDataResponse = {
   data: unknown
 }
 
+export type DashboardMutationResponse = {
+  ok: boolean
+  error?: string
+  groupId?: string
+  widgetId?: string
+}
+
 export type DashboardWidgetDataRequest = {
   pagination?: {
     page: number
@@ -119,6 +126,36 @@ async function callDashboardApi(path: string, body: Record<string, unknown>): Pr
   }
 }
 
+async function callDashboardMutationApi(path: string, body: Record<string, unknown>): Promise<DashboardMutationResponse> {
+  const rawResponse = await fetch(path, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'accept-language': localStorage.getItem('af_lang') || 'en',
+    },
+    body: JSON.stringify(body),
+  })
+
+  const response = await parseDashboardResponse(rawResponse)
+
+  if (!rawResponse.ok) {
+    throw new DashboardApiError(
+      response?.error || rawResponse.statusText || `Dashboard request failed (${rawResponse.status})`,
+      normalizeValidationErrors(response),
+    )
+  }
+
+  if (!response || response.error || response.ok === false) {
+    throw new DashboardApiError(response?.error || 'Dashboard request failed', normalizeValidationErrors(response))
+  }
+
+  return {
+    ok: true,
+    groupId: response.groupId,
+    widgetId: response.widgetId,
+  }
+}
+
 async function callDashboardWidgetDataApi(
   path: string,
   body: Record<string, unknown>,
@@ -156,39 +193,39 @@ export const dashboardApi = {
     return callDashboardApi('/adminapi/v1/dashboard/get-config', { slug })
   },
 
-  async addDashboardGroup(slug: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/add_dashboard_group', { slug })
+  async addDashboardGroup(slug: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/add_dashboard_group', { slug })
   },
 
   async moveDashboardGroup(
     slug: string,
     groupId: string,
     direction: DashboardGroupMoveDirection,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/move_dashboard_group', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/move_dashboard_group', {
       slug,
       groupId,
       direction,
     })
   },
 
-  async removeDashboardGroup(slug: string, groupId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/remove_dashboard_group', {
+  async removeDashboardGroup(slug: string, groupId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/remove_dashboard_group', {
       slug,
       groupId,
     })
   },
 
-  async setDashboardGroupConfig(slug: string, groupId: string, config: EditableDashboardGroupConfig): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/set_dashboard_group_config', {
+  async setDashboardGroupConfig(slug: string, groupId: string, config: EditableDashboardGroupConfig): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/set_dashboard_group_config', {
       slug,
       groupId,
       config,
     })
   },
 
-  async addDashboardWidget(slug: string, groupId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/add_dashboard_widget', {
+  async addDashboardWidget(slug: string, groupId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/add_dashboard_widget', {
       slug,
       groupId,
     })
@@ -198,23 +235,23 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     direction: DashboardWidgetMoveDirection,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/move_dashboard_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/move_dashboard_widget', {
       slug,
       widgetId,
       direction,
     })
   },
 
-  async removeDashboardWidget(slug: string, widgetId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/remove_dashboard_widget', {
+  async removeDashboardWidget(slug: string, widgetId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/remove_dashboard_widget', {
       slug,
       widgetId,
     })
   },
 
-  async setWidgetConfig(slug: string, widgetId: string, config: unknown): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/set_widget_config', {
+  async setWidgetConfig(slug: string, widgetId: string, config: unknown): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/set_widget_config', {
       slug,
       widgetId,
       config,
@@ -225,8 +262,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableTableWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_table_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_table_widget', {
       slug,
       widgetId,
       config,
@@ -237,8 +274,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableKpiCardWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_kpi_card_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_kpi_card_widget', {
       slug,
       widgetId,
       config,
@@ -249,8 +286,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableGaugeCardWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_gauge_card_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_gauge_card_widget', {
       slug,
       widgetId,
       config,
@@ -261,8 +298,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableLineChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_line_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_line_chart_widget', {
       slug,
       widgetId,
       config,
@@ -273,8 +310,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableBarChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_bar_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_bar_chart_widget', {
       slug,
       widgetId,
       config,
@@ -285,8 +322,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableStackedBarChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_stacked_bar_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_stacked_bar_chart_widget', {
       slug,
       widgetId,
       config,
@@ -297,8 +334,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurablePieChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_pie_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_pie_chart_widget', {
       slug,
       widgetId,
       config,
@@ -309,8 +346,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableHistogramChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_histogram_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_histogram_chart_widget', {
       slug,
       widgetId,
       config,
@@ -321,8 +358,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableFunnelChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_funnel_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_funnel_chart_widget', {
       slug,
       widgetId,
       config,
@@ -333,8 +370,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurablePivotTableWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_pivot_table_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_pivot_table_widget', {
       slug,
       widgetId,
       config,

package/custom/runtime/DashboardRuntime.vue

@@ -286,7 +286,8 @@ async function addGroup() {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.addDashboardGroup(props.dashboardSlug))
+    await dashboardApi.addDashboardGroup(props.dashboardSlug)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to add dashboard group', error)
   }
@@ -298,7 +299,8 @@ async function addWidget(groupId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.addDashboardWidget(props.dashboardSlug, groupId))
+    await dashboardApi.addDashboardWidget(props.dashboardSlug, groupId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to add dashboard widget', error)
   }
@@ -310,9 +312,8 @@ async function moveGroup(groupId: string, direction: DashboardGroupMoveDirection
   }
 
   try {
-    applyDashboardResponse(
-      await dashboardApi.moveDashboardGroup(props.dashboardSlug, groupId, direction),
-    )
+    await dashboardApi.moveDashboardGroup(props.dashboardSlug, groupId, direction)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to move dashboard group', error)
   }
@@ -324,7 +325,8 @@ async function removeGroup(groupId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.removeDashboardGroup(props.dashboardSlug, groupId))
+    await dashboardApi.removeDashboardGroup(props.dashboardSlug, groupId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to remove dashboard group', error)
   }
@@ -348,13 +350,12 @@ async function saveGroupConfig() {
   try {
     const groupConfig = parseYaml(groupConfigCode.value) as EditableDashboardGroupConfig
 
-    applyDashboardResponse(
-      await dashboardApi.setDashboardGroupConfig(
-        props.dashboardSlug,
-        editingGroupId.value,
-        groupConfig,
-      ),
+    await dashboardApi.setDashboardGroupConfig(
+      props.dashboardSlug,
+      editingGroupId.value,
+      groupConfig,
     )
+    await refreshDashboardConfig()
     closeGroupConfigEditor()
   } catch (error) {
     groupConfigError.value = error instanceof Error ? error.message : 'Invalid group config'
@@ -373,9 +374,8 @@ async function moveWidget(widgetId: string, direction: DashboardWidgetMoveDirect
   }
 
   try {
-    applyDashboardResponse(
-      await dashboardApi.moveDashboardWidget(props.dashboardSlug, widgetId, direction),
-    )
+    await dashboardApi.moveDashboardWidget(props.dashboardSlug, widgetId, direction)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to move dashboard widget', error)
   }
@@ -387,7 +387,8 @@ async function removeWidget(widgetId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.removeDashboardWidget(props.dashboardSlug, widgetId))
+    await dashboardApi.removeDashboardWidget(props.dashboardSlug, widgetId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to remove dashboard widget', error)
   }
@@ -410,13 +411,12 @@ async function saveWidgetConfig() {
     widgetConfigFieldErrors.value = []
     const widgetConfig = parseYaml(widgetConfigCode.value) as DashboardWidgetConfig
 
-    applyDashboardResponse(
-      await dashboardApi.setWidgetConfig(
-        props.dashboardSlug,
-        editingWidgetId.value,
-        serializeDashboardWidgetConfigForEditor(widgetConfig),
-      ),
+    await dashboardApi.setWidgetConfig(
+      props.dashboardSlug,
+      editingWidgetId.value,
+      serializeDashboardWidgetConfigForEditor(widgetConfig),
     )
+    await refreshDashboardConfig()
     closeWidgetConfigEditor()
   } catch (error) {
     widgetConfigError.value = error instanceof Error ? error.message : 'Invalid widget config'
@@ -431,6 +431,10 @@ function closeWidgetConfigEditor() {
   widgetConfigFieldErrors.value = []
 }
 
+async function refreshDashboardConfig() {
+  applyDashboardResponse(await dashboardApi.getDashboardConfig(props.dashboardSlug))
+}
+
 function applyDashboardResponse(response: DashboardResponse) {
   draftConfig.value = cloneConfig(response.config)
   currentRevision.value = response.revision

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

@@ -22,26 +22,320 @@ Dashboard root, groups, and widgets are different entities.
 
 ## Tool routing
 
+- Get dashboard slugs: dashboard_get_slugs
 - Read dashboard: dashboard_get_config
 - Add group: dashboard_add_dashboard_group
 - Rename group: dashboard_set_dashboard_group_config
 - Add widget slot: dashboard_add_dashboard_widget
-- Configure table widget: dashboard_configure_table_widget
-- Configure KPI card widget: dashboard_configure_kpi_card_widget
-- Configure gauge card widget: dashboard_configure_gauge_card_widget
-- Configure line chart widget: dashboard_configure_line_chart_widget
-- Configure bar chart widget: dashboard_configure_bar_chart_widget
-- Configure stacked bar chart widget: dashboard_configure_stacked_bar_chart_widget
-- Configure pie chart widget: dashboard_configure_pie_chart_widget
-- Configure histogram chart widget: dashboard_configure_histogram_chart_widget
-- Configure funnel chart widget: dashboard_configure_funnel_chart_widget
-- Configure pivot table widget: dashboard_configure_pivot_table_widget
+- Configure widget:
+  - table: dashboard_configure_table_widget
+  - kpi_card: dashboard_configure_kpi_card_widget
+  - gauge_card: dashboard_configure_gauge_card_widget
+  - pivot_table: dashboard_configure_pivot_table_widget
+  - line_chart: dashboard_configure_line_chart_widget
+  - bar_chart: dashboard_configure_bar_chart_widget
+  - stacked_bar_chart: dashboard_configure_stacked_bar_chart_widget
+  - pie_chart: dashboard_configure_pie_chart_widget
+  - histogram_chart: dashboard_configure_histogram_chart_widget
+  - funnel_chart: dashboard_configure_funnel_chart_widget
 - Move/remove widget/group: matching move/remove tool
 - Load widget data: dashboard_get_dashboard_widget_data
 
 If a known dashboard tool schema is missing, call fetch_tool_schema for that exact tool.
 If fetch_tool_schema returns but the intended tool is still not callable, stop and report a tool-routing error. Do not substitute another mutation tool.
 
+## Configure schema examples
+
+These examples show the expected shape only. Do not copy them one-to-one: adapt resource names, fields, aggregations, labels, filters, formats, and calculations to the actual dashboard request and available resource columns.
+
+Important:
+- `config.target` is the widget target, never a resource path.
+- Never use values like `/resource/llm_usage` in `config.target`.
+- Put the data resource in `config.query.resource`, for example `query.resource: "llm_usage"`.
+- For chart widgets, `config.target` is always `chart`; the concrete chart kind is `config.chart.type`.
+- `query.calcs[].calc` is an expression over already selected fields/aliases, not raw SQL. Do not use SQL syntax such as `CASE WHEN`.
+
+Example `dashboard_configure_table_widget` config:
+
+```yaml
+target: table
+label: Recent usage
+size: wide
+table:
+  columns:
+    - field: used_at
+      label: Date
+    - field: model
+      label: Model
+    - field: total_tokens
+      label: Tokens
+      format: integer
+  pagination: true
+  page_size: 20
+query:
+  resource: llm_usage
+  select:
+    - field: used_at
+    - field: model
+    - field: total_tokens
+  order_by:
+    - field: used_at
+      direction: desc
+```
+
+Example `dashboard_configure_kpi_card_widget` config:
+
+```yaml
+target: kpi_card
+label: Total spend
+size: medium
+card:
+  title: Total spend
+  value:
+    field: spend
+    format: currency
+query:
+  resource: llm_usage
+  select:
+    - agg: sum
+      field: cost
+      as: spend
+```
+
+Example `dashboard_configure_gauge_card_widget` config:
+
+```yaml
+target: gauge_card
+label: Budget usage
+size: medium
+card:
+  title: Budget usage
+  value:
+    field: spend
+    format: currency
+  progress:
+    value_field: spend
+    target_value: 1000
+    format: percent
+query:
+  resource: llm_usage
+  select:
+    - agg: sum
+      field: cost
+      as: spend
+```
+
+Example `dashboard_configure_pivot_table_widget` config:
+
+```yaml
+target: pivot_table
+label: Spend by model and purpose
+size: wide
+pivot:
+  rows:
+    - field: model
+      label: Model
+  columns:
+    - field: purpose
+      label: Purpose
+  values:
+    - field: spend
+      label: Spend
+      format: currency
+      aggregation: sum
+query:
+  resource: llm_usage
+  select:
+    - field: model
+    - field: purpose
+    - agg: sum
+      field: cost
+      as: spend
+  group_by:
+    - model
+    - purpose
+```
+
+Example `dashboard_configure_line_chart_widget` config:
+
+```yaml
+target: chart
+label: Daily spend
+size: wide
+chart:
+  type: line
+  x:
+    field: day
+    label: Day
+  y:
+    - field: spend
+      label: Spend
+      format: currency
+query:
+  resource: llm_usage
+  select:
+    - field: used_at
+      grain: day
+      as: day
+    - agg: sum
+      field: cost
+      as: spend
+  group_by:
+    - field: used_at
+      grain: day
+      as: day
+  order_by:
+    - field: day
+      direction: asc
+```
+
+Example `dashboard_configure_bar_chart_widget` config:
+
+```yaml
+target: chart
+label: Spend by model
+size: wide
+chart:
+  type: bar
+  x:
+    field: model
+    label: Model
+  y:
+    field: spend
+    label: Spend
+    format: currency
+query:
+  resource: llm_usage
+  select:
+    - field: model
+    - agg: sum
+      field: cost
+      as: spend
+  group_by:
+    - model
+```
+
+Example `dashboard_configure_stacked_bar_chart_widget` config:
+
+```yaml
+target: chart
+label: Daily spend by purpose
+size: wide
+chart:
+  type: stacked_bar
+  x:
+    field: day
+    label: Day
+  y:
+    field: spend
+    label: Spend
+    format: currency
+  series:
+    field: purpose
+    label: Purpose
+query:
+  resource: llm_usage
+  select:
+    - field: used_at
+      grain: day
+      as: day
+    - field: purpose
+    - agg: sum
+      field: cost
+      as: spend
+  group_by:
+    - field: used_at
+      grain: day
+      as: day
+    - purpose
+  order_by:
+    - field: day
+      direction: asc
+```
+
+Example `dashboard_configure_pie_chart_widget` config:
+
+```yaml
+target: chart
+label: Spend share by model
+size: medium
+chart:
+  type: pie
+  label:
+    field: model
+    label: Model
+  value:
+    field: spend
+    label: Spend
+    format: currency
+query:
+  resource: llm_usage
+  select:
+    - field: model
+    - agg: sum
+      field: cost
+      as: spend
+  group_by:
+    - model
+```
+
+Example `dashboard_configure_histogram_chart_widget` config:
+
+```yaml
+target: chart
+label: Request size distribution
+size: wide
+chart:
+  type: histogram
+  x:
+    field: total_tokens
+    label: Tokens
+  y:
+    field: requests
+    label: Requests
+query:
+  resource: llm_usage
+  select:
+    - field: total_tokens
+    - agg: count
+      as: requests
+  bucket:
+    field: total_tokens
+    buckets:
+      - label: Small
+        max: 1000
+      - label: Medium
+        min: 1000
+        max: 10000
+      - label: Large
+        min: 10000
+```
+
+Example `dashboard_configure_funnel_chart_widget` config:
+
+```yaml
+target: chart
+label: Request funnel
+size: wide
+chart:
+  type: funnel
+  label:
+    field: stage
+    label: Stage
+  value:
+    field: count
+    label: Count
+query:
+  resource: llm_usage
+  select:
+    - field: stage
+    - agg: count
+      as: count
+  group_by:
+    - stage
+```
+
+
 ## Group creation guard
 
 Before creating a group, call dashboard_get_config and check existing groups.
@@ -148,6 +442,7 @@ Use target, not type.
 For charts, use target: chart and chart.type for the concrete chart kind.
 Use query, not dataSource.
 Use resource, not resourceId.
+Never use AdminForth routes such as /resource/llm_usage as resource or target values.
 
 ## Query shape rules