@adminforth/dashboard 1.9.0 → 1.11.0

package/dist/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
 

package/dist/endpoint/dashboard.d.ts

@@ -3,6 +3,7 @@ import type { DashboardConfig } from '../custom/model/dashboard.types.js';
 import type { DashboardRecord } from '../services/dashboardConfigService.js';
 type DashboardEndpointsContext = {
     getDashboardRecord: (slug: string) => Promise<DashboardRecord | null>;
+    getAllDashboardRecords: () => Promise<DashboardRecord[]>;
     parseStoredDashboardConfig: (config: unknown) => DashboardConfig;
 };
 export declare function registerDashboardEndpoints(server: IHttpServer, ctx: DashboardEndpointsContext): void;

package/dist/endpoint/dashboard.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { DashboardApiResponseSchema, SlugRequestSchema, } from '../schema/api.js';
+import { DashboardApiResponseSchema, GetSlugsResponseSchema, SlugRequestSchema, } from '../schema/api.js';
 export function registerDashboardEndpoints(server, ctx) {
     server.endpoint({
         method: 'POST',
@@ -30,4 +30,18 @@ export function registerDashboardEndpoints(server, ctx) {
             };
         }),
     });
+    server.endpoint({
+        method: 'GET',
+        path: '/dashboard/get-slugs',
+        description: 'Returns a list of all dashboard slugs and labels for listing purposes.',
+        request_schema: undefined,
+        response_schema: GetSlugsResponseSchema,
+        handler: () => __awaiter(this, void 0, void 0, function* () {
+            const dashboards = yield ctx.getAllDashboardRecords();
+            return dashboards.map((dashboard) => ({
+                slug: dashboard.slug,
+                label: dashboard.label,
+            }));
+        }),
+    });
 }

package/dist/endpoint/groups.js

@@ -8,19 +8,20 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { randomUUID } from 'crypto';
-import { DashboardApiResponseSchema, GroupIdRequestSchema, MoveGroupRequestSchema, SetGroupConfigRequestSchema, SlugRequestSchema, } from '../schema/api.js';
+import { DashboardMutationResponseSchema, GroupIdRequestSchema, MoveGroupRequestSchema, SetGroupConfigRequestSchema, SlugRequestSchema, } from '../schema/api.js';
 export function registerGroupEndpoints(server, ctx) {
     server.endpoint({
         method: 'POST',
         path: '/dashboard/add_dashboard_group',
         description: 'Adds a new group to a dashboard configuration. Superadmin only.',
         request_schema: SlugRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
+            let groupId = null;
             const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
                 const nextOrder = config.groups.length + 1;
                 const group = {
@@ -28,13 +29,14 @@ export function registerGroupEndpoints(server, ctx) {
                     label: 'New group',
                     order: nextOrder,
                 };
+                groupId = group.id;
                 return Object.assign(Object.assign({}, config), { groups: [...config.groups, group] });
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
-            return updatedDashboard;
+            return { ok: true, groupId };
         }),
     });
     server.endpoint({
@@ -42,11 +44,11 @@ export function registerGroupEndpoints(server, ctx) {
         path: '/dashboard/set_dashboard_group_config',
         description: 'Replaces editable JSON configuration for a dashboard group while preserving group id and order. Superadmin only.',
         request_schema: SetGroupConfigRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             const groupId = body.groupId;
             let mutationError = null;
@@ -63,13 +65,13 @@ export function registerGroupEndpoints(server, ctx) {
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
     server.endpoint({
@@ -77,11 +79,11 @@ export function registerGroupEndpoints(server, ctx) {
         path: '/dashboard/move_dashboard_group',
         description: 'Moves a dashboard group up or down in its dashboard. Superadmin only.',
         request_schema: MoveGroupRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             let mutationError = null;
             const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
@@ -102,13 +104,13 @@ export function registerGroupEndpoints(server, ctx) {
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
     server.endpoint({
@@ -116,11 +118,11 @@ export function registerGroupEndpoints(server, ctx) {
         path: '/dashboard/remove_dashboard_group',
         description: 'Removes a dashboard group and all widgets inside it. Superadmin only.',
         request_schema: GroupIdRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             const groupId = body.groupId;
             let mutationError = null;
@@ -134,13 +136,13 @@ export function registerGroupEndpoints(server, ctx) {
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
 }

package/dist/endpoint/widgets.js

@@ -8,7 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { randomUUID } from 'crypto';
-import { ConfigureBarChartWidgetRequestSchema, ConfigureFunnelChartWidgetRequestSchema, ConfigureGaugeCardWidgetRequestSchema, ConfigureHistogramChartWidgetRequestSchema, ConfigureKpiCardWidgetRequestSchema, ConfigureLineChartWidgetRequestSchema, ConfigurePieChartWidgetRequestSchema, ConfigurePivotTableWidgetRequestSchema, ConfigureStackedBarChartWidgetRequestSchema, ConfigureTableWidgetRequestSchema, DashboardApiResponseSchema, DashboardWidgetDataResponseSchema, GroupIdRequestSchema, MoveWidgetRequestSchema, SetWidgetConfigRequestSchema, WidgetDataRequestSchema, WidgetIdRequestSchema, } from '../schema/api.js';
+import { ConfigureBarChartWidgetRequestSchema, ConfigureFunnelChartWidgetRequestSchema, ConfigureGaugeCardWidgetRequestSchema, ConfigureHistogramChartWidgetRequestSchema, ConfigureKpiCardWidgetRequestSchema, ConfigureLineChartWidgetRequestSchema, ConfigurePieChartWidgetRequestSchema, ConfigurePivotTableWidgetRequestSchema, ConfigureStackedBarChartWidgetRequestSchema, ConfigureTableWidgetRequestSchema, DashboardMutationResponseSchema, DashboardWidgetDataResponseSchema, GroupIdRequestSchema, MoveWidgetRequestSchema, SetWidgetConfigRequestSchema, WidgetDataRequestSchema, WidgetIdRequestSchema, } from '../schema/api.js';
 function replaceWidgetConfig(ctx, slug, widgetId, widgetConfig) {
     return __awaiter(this, void 0, void 0, function* () {
         let mutationError = null;
@@ -35,23 +35,23 @@ function registerConfigureWidgetEndpoint(server, ctx, options) {
         path: options.path,
         description: options.description,
         request_schema: options.requestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             const request = body;
             const { updatedDashboard, mutationError } = yield replaceWidgetConfig(ctx, request.slug, request.widgetId, request.config);
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
 }
@@ -61,13 +61,14 @@ export function registerWidgetEndpoints(server, ctx) {
         path: '/dashboard/add_dashboard_widget',
         description: 'Adds a new empty widget to a dashboard group. Superadmin only.',
         request_schema: GroupIdRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             let mutationError = null;
+            let widgetId = null;
             const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
                 const group = config.groups.find((item) => item.id === body.groupId);
                 if (!group) {
@@ -83,17 +84,18 @@ export function registerWidgetEndpoints(server, ctx) {
                     order: nextOrder,
                     target: 'empty',
                 };
+                widgetId = widget.id;
                 return Object.assign(Object.assign({}, config), { widgets: [...config.widgets, widget] });
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true, widgetId };
         }),
     });
     server.endpoint({
@@ -101,11 +103,11 @@ export function registerWidgetEndpoints(server, ctx) {
         path: '/dashboard/move_dashboard_widget',
         description: 'Moves a dashboard widget up or down inside its group. Superadmin only.',
         request_schema: MoveWidgetRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             let mutationError = null;
             const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
@@ -133,13 +135,13 @@ export function registerWidgetEndpoints(server, ctx) {
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
     server.endpoint({
@@ -147,11 +149,11 @@ export function registerWidgetEndpoints(server, ctx) {
         path: '/dashboard/remove_dashboard_widget',
         description: 'Removes one dashboard widget by id. Superadmin only.',
         request_schema: WidgetIdRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             let mutationError = null;
             const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
@@ -164,13 +166,13 @@ export function registerWidgetEndpoints(server, ctx) {
             });
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
     server.endpoint({
@@ -178,23 +180,23 @@ export function registerWidgetEndpoints(server, ctx) {
         path: '/dashboard/set_widget_config',
         description: 'Replaces editable JSON configuration for a dashboard widget while preserving widget id, group id, and order. Superadmin only.',
         request_schema: SetWidgetConfigRequestSchema,
-        response_schema: DashboardApiResponseSchema,
+        response_schema: DashboardMutationResponseSchema,
         handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
             if (!ctx.canEditDashboard(adminUser)) {
                 response.setStatus(403);
-                return { error: 'Dashboard edit is not allowed' };
+                return { ok: false, error: 'Dashboard edit is not allowed' };
             }
             const request = body;
             const { updatedDashboard, mutationError } = yield replaceWidgetConfig(ctx, request.slug, request.widgetId, request.config);
             if (!updatedDashboard) {
                 response.setStatus(404);
-                return { error: 'Dashboard not found' };
+                return { ok: false, error: 'Dashboard not found' };
             }
             if (mutationError) {
                 response.setStatus(404);
-                return { error: mutationError };
+                return { ok: false, error: mutationError };
             }
-            return updatedDashboard;
+            return { ok: true };
         }),
     });
     registerConfigureWidgetEndpoint(server, ctx, {