@carthooks/arcubase-cli 0.1.21 → 0.1.22

package/sdk-dist/docs/runtime-reference/help-examples/admin/widget/create.json

@@ -0,0 +1,33 @@
+{
+  "scope": "admin",
+  "command": ["widget", "create"],
+  "examples": [
+    {
+      "title": "create a dashboard chart widget",
+      "body": {
+        "type": "chart",
+        "options": {
+          "dashboard_id": 2188892001
+        }
+      },
+      "notes": [
+        "do not set options.type by hand",
+        "dashboard_id selects a dashboard widget",
+        "use widget update next to save chart options"
+      ]
+    },
+    {
+      "title": "create an ingress list widget",
+      "body": {
+        "type": "list",
+        "options": {
+          "ingress_id": 2188893001
+        }
+      },
+      "notes": [
+        "ingress_id selects an ingress widget",
+        "do not place ingress widgets with dashboard update-layout"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/widget/preview-data.json

@@ -0,0 +1,42 @@
+{
+  "scope": "admin",
+  "command": ["widget", "preview-data"],
+  "examples": [
+    {
+      "title": "preview dashboard chart data from a table",
+      "body": {
+        "dataSource": 2188891001,
+        "dataSourceType": "entity",
+        "dimensions": [
+          {"IsField": true, "FieldID": 1004, "Name": "Source"}
+        ],
+        "measures": [
+          {"FieldID": 1005, "Aggregate": "sum", "Name": "Total Amount"}
+        ]
+      },
+      "notes": [
+        "preview-data does not accept --widget-id",
+        "do not send widget_id or id in the request body",
+        "copy dimensions and measures from the chart query you want to preview"
+      ]
+    },
+    {
+      "title": "preview count and distinct_count in one grouped chart",
+      "body": {
+        "dataSource": 2188891001,
+        "dataSourceType": "entity",
+        "dimensions": [
+          {"IsField": true, "FieldID": 1004, "Name": "Source"}
+        ],
+        "measures": [
+          {"Aggregate": "count", "Name": "Lead Count"},
+          {"FieldID": 1002, "Aggregate": "distinct_count", "Name": "Distinct Customers"}
+        ]
+      },
+      "notes": [
+        "supported Aggregate values are sum, avg, max, min, count, and distinct_count",
+        "unsupported aggregate names fail local body validation before the request is sent"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/widgets.md

@@ -0,0 +1,40 @@
+# Widgets
+
+Use `arcubase-admin widget list --app-id <app_id> --type dashboard --dashboard-id <dashboard_id>` to list dashboard widgets.
+
+Use `arcubase-admin widget get`, `arcubase-admin widget create`, `arcubase-admin widget update`, `arcubase-admin widget update-ingress-options`, `arcubase-admin widget preview-data`, and `arcubase-admin widget delete` to manage widgets.
+
+Use `arcubase widget data --app-id <app_id> --body-json '<FetchWidgetsDataReqVO>'` to fetch user-visible widget data.
+
+Create dashboard widgets with `{"type":"chart","options":{"dashboard_id":<dashboard_id>}}`. Do not set `options.type` by hand; the backend derives dashboard versus ingress widget type from `dashboard_id` or `ingress_id`.
+
+Most widget commands use `--widget-id`; `widget preview-data` is the exception. Preview data does not read a saved widget by id and does not accept `--widget-id`, `widget_id`, or `id`. Its body is the chart query itself:
+
+```json
+{"dataSource":2188891001,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":1004,"Name":"Source"}],"measures":[{"FieldID":1005,"Aggregate":"sum","Name":"Total Amount"}]}
+```
+
+Field dimensions must set `IsField:true`. If `IsField` is omitted or false while `FieldID` is present, the CLI rejects the chart request before sending it. A saved chart returned by `widget get` or `widget list` with `FieldID` and `IsField:false` is not grouped by that field; update the chart before reading grouped statistics.
+
+Fastfail rule: `widget preview-data` accepts only the chart query body. If validation reports unrecognized keys such as `id`, `entity_id`, or `options`, do not retry with a saved widget object. Retry with `dataSource`, `dataSourceType`, `dimensions`, `measures`, and optional `conditions` only.
+
+After `widget update`, verify persistence with `widget get` or `widget list`. The saved widget must contain non-null `options.charts`; an update response alone is not enough evidence that the chart configuration was persisted.
+
+## Chart measures
+
+Dashboard chart widgets use `ChartOption.measures[]` to define statistics. Supported `Aggregate` values are:
+
+| Aggregate | Meaning |
+| --- | --- |
+| `sum` | Sum the selected numeric field. |
+| `avg` | Average the selected numeric field. |
+| `max` | Return the maximum selected field value. |
+| `min` | Return the minimum selected field value. |
+| `count` | Count selected field values; if `FieldID` is omitted, count rows. |
+| `distinct_count` | Count distinct selected field values. |
+
+Multiple measures are allowed in one chart widget. Use stable `Name` aliases so the returned data can be read without guessing.
+
+Fastfail rule: unsupported aggregate names are invalid request bodies. Do not silently rewrite them to `count`, do not retry with a guessed aggregate, and do not save the widget until the `Aggregate` value is one of the supported values above.
+
+Grouped-statistics evidence must include the requested dimension column in returned rows. If `widget preview-data` or user-side `widget data` returns only measure columns such as totals and counts, that is total-only data, not grouped data.

package/sdk-dist/generated/command_registry.generated.ts

@@ -167,6 +167,148 @@ export const adminCommands = [
     "queryParams": [],
     "responseType": "boolean"
   },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "getDashboardList",
+    "commandPath": [
+      "dashboard",
+      "list"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:app_id/dashboard",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "Dashboard.GetList",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "DashboardGetListRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "createDashboard",
+    "commandPath": [
+      "dashboard",
+      "create"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/:app_id/dashboard",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "Dashboard.Create",
+    "requestType": "DashboardCreateReqVO",
+    "queryParams": [],
+    "responseType": "DashboardCreateRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "getDashboardOptions",
+    "commandPath": [
+      "dashboard",
+      "get-options"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:app_id/dashboard/:dashboard_id/options",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "Dashboard.FetchOptions",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "DashboardFetchOptionsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "updateDashboardOptions",
+    "commandPath": [
+      "dashboard",
+      "update-options"
+    ],
+    "method": "PUT",
+    "endpoint": "/api/apps/:app_id/dashboard/:dashboard_id/options",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "Dashboard.UpdateOptions",
+    "requestType": "DashboardUpdateOptionsReqVO",
+    "queryParams": [],
+    "responseType": "DashboardUpdateOptionsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "updateDashboardLayout",
+    "commandPath": [
+      "dashboard",
+      "update-layout"
+    ],
+    "method": "PUT",
+    "endpoint": "/api/apps/:app_id/dashboard/:dashboard_id/layout",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "Dashboard.UpdateLayout",
+    "requestType": "DashboardUpdateLayoutReqVO",
+    "queryParams": [],
+    "responseType": "DashboardUpdateLayoutRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "dashboard",
+    "functionName": "updateDashboardTitle",
+    "commandPath": [
+      "dashboard",
+      "rename"
+    ],
+    "method": "PUT",
+    "endpoint": "/api/apps/:app_id/dashboard/:dashboard_id/label",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "Dashboard.UpdateTitle",
+    "requestType": "DashboardUpdateTitleReqVO",
+    "queryParams": [],
+    "responseType": "DashboardUpdateTitleRespVO"
+  },
   {
     "scope": "admin",
     "module": "table",
@@ -602,6 +744,188 @@ export const adminCommands = [
     "requestType": "EntityWorkflowUpdateReqVO",
     "queryParams": [],
     "responseType": "EntityWorkflowUpdateRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "widgetsList",
+    "commandPath": [
+      "widget",
+      "list"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:app_id/widgets",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "App.WidgetsList",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "type",
+        "flag": "type",
+        "type": "string",
+        "hasDefault": true
+      },
+      {
+        "key": "dashboard_id",
+        "flag": "dashboard-id",
+        "type": "number",
+        "hasDefault": true
+      },
+      {
+        "key": "ingress_id",
+        "flag": "ingress-id",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "AppWidgetsListRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "getWidgets",
+    "commandPath": [
+      "widget",
+      "get"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:app_id/widgets/:widgets_id",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "widgets_id",
+        "flag": "widget-id"
+      }
+    ],
+    "controller": "App.GetWidgets",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "AppGetWidgetsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "newWidgets",
+    "commandPath": [
+      "widget",
+      "create"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/:app_id/widgets",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "App.NewWidgets",
+    "requestType": "AppNewWidgetsReqVO",
+    "queryParams": [],
+    "responseType": "AppNewWidgetsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "updateWidgets",
+    "commandPath": [
+      "widget",
+      "update"
+    ],
+    "method": "PUT",
+    "endpoint": "/api/apps/:app_id/widgets/:widgets_id",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "widgets_id",
+        "flag": "widget-id"
+      }
+    ],
+    "controller": "App.UpdateWidgets",
+    "requestType": "AppUpdateWidgetsReqVO",
+    "queryParams": [],
+    "responseType": "AppUpdateWidgetsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "updateWidgetsIngressOptions",
+    "commandPath": [
+      "widget",
+      "update-ingress-options"
+    ],
+    "method": "PUT",
+    "endpoint": "/api/apps/:app_id/widgets/:widgets_id/ingress-options",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "widgets_id",
+        "flag": "widget-id"
+      }
+    ],
+    "controller": "App.UpdateWidgetsIngressOptions",
+    "requestType": "AppUpdateWidgetsIngressOptionsReqVO",
+    "queryParams": [],
+    "responseType": "AppUpdateWidgetsIngressOptionsRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "previewWidgetsData",
+    "commandPath": [
+      "widget",
+      "preview-data"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/:app_id/widgets-preview",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "App.PreviewWidgetsData",
+    "requestType": "AppPreviewWidgetsDataReqVO",
+    "queryParams": [],
+    "responseType": "AppPreviewWidgetsDataRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "widget",
+    "functionName": "deleteWidgets",
+    "commandPath": [
+      "widget",
+      "delete"
+    ],
+    "method": "DELETE",
+    "endpoint": "/api/apps/:app_id/widgets/:widgets_id",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "widgets_id",
+        "flag": "widget-id"
+      }
+    ],
+    "controller": "App.DeleteWidgets",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "boolean"
   }
 ] as const
 
@@ -629,6 +953,56 @@ export const userCommands = [
     ],
     "responseType": "GlobalActionEntryRespVO"
   },
+  {
+    "scope": "user",
+    "module": "dashboard",
+    "functionName": "getDashboard",
+    "commandPath": [
+      "dashboard",
+      "get"
+    ],
+    "method": "GET",
+    "endpoint": "/api/dashboard/:app_id/:dashboard_id",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "UserAction.DashboardGet",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "DashboardGetRespVO"
+  },
+  {
+    "scope": "user",
+    "module": "dashboard",
+    "functionName": "getDashboardWidgets",
+    "commandPath": [
+      "dashboard",
+      "widgets"
+    ],
+    "method": "GET",
+    "endpoint": "/api/dashboard/:app_id/:dashboard_id/widgets",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "dashboard_id",
+        "flag": "dashboard-id"
+      }
+    ],
+    "controller": "UserAction.DashboardWidgets",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "DashboardWidgets[]"
+  },
   {
     "scope": "user",
     "module": "table",
@@ -1050,6 +1424,27 @@ export const userCommands = [
     "queryParams": [],
     "responseType": "MobileUploadCheckRespVO"
   },
+  {
+    "scope": "user",
+    "module": "widget",
+    "functionName": "fetchWidgetsData",
+    "commandPath": [
+      "widget",
+      "data"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/:app_id/widgets-data",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "UserAction.FetchWidgetsData",
+    "requestType": "FetchWidgetsDataReqVO",
+    "queryParams": [],
+    "responseType": "FetchWidgetsDataRespVO"
+  },
   {
     "scope": "user",
     "module": "profile",

package/sdk-dist/generated/help_examples.generated.ts

@@ -346,6 +346,128 @@ export const helpExamplesIndex = {
       }
     ]
   },
+  "admin.dashboard.update-layout": {
+    "command": [
+      "dashboard",
+      "update-layout"
+    ],
+    "examples": [
+      {
+        "title": "place one dashboard widget in the top-left area",
+        "body": [
+          {
+            "id": 2188892001,
+            "x": 0,
+            "y": 0,
+            "w": 12,
+            "h": 6
+          }
+        ],
+        "notes": [
+          "the request body is a top-level array",
+          "do not wrap the array as {\"layout\":[...]}"
+        ]
+      }
+    ]
+  },
+  "admin.widget.create": {
+    "command": [
+      "widget",
+      "create"
+    ],
+    "examples": [
+      {
+        "title": "create a dashboard chart widget",
+        "body": {
+          "type": "chart",
+          "options": {
+            "dashboard_id": 2188892001
+          }
+        },
+        "notes": [
+          "do not set options.type by hand",
+          "dashboard_id selects a dashboard widget",
+          "use widget update next to save chart options"
+        ]
+      },
+      {
+        "title": "create an ingress list widget",
+        "body": {
+          "type": "list",
+          "options": {
+            "ingress_id": 2188893001
+          }
+        },
+        "notes": [
+          "ingress_id selects an ingress widget",
+          "do not place ingress widgets with dashboard update-layout"
+        ]
+      }
+    ]
+  },
+  "admin.widget.preview-data": {
+    "command": [
+      "widget",
+      "preview-data"
+    ],
+    "examples": [
+      {
+        "title": "preview dashboard chart data from a table",
+        "body": {
+          "dataSource": 2188891001,
+          "dataSourceType": "entity",
+          "dimensions": [
+            {
+              "IsField": true,
+              "FieldID": 1004,
+              "Name": "Source"
+            }
+          ],
+          "measures": [
+            {
+              "FieldID": 1005,
+              "Aggregate": "sum",
+              "Name": "Total Amount"
+            }
+          ]
+        },
+        "notes": [
+          "preview-data does not accept --widget-id",
+          "do not send widget_id or id in the request body",
+          "copy dimensions and measures from the chart query you want to preview"
+        ]
+      },
+      {
+        "title": "preview count and distinct_count in one grouped chart",
+        "body": {
+          "dataSource": 2188891001,
+          "dataSourceType": "entity",
+          "dimensions": [
+            {
+              "IsField": true,
+              "FieldID": 1004,
+              "Name": "Source"
+            }
+          ],
+          "measures": [
+            {
+              "Aggregate": "count",
+              "Name": "Lead Count"
+            },
+            {
+              "FieldID": 1002,
+              "Aggregate": "distinct_count",
+              "Name": "Distinct Customers"
+            }
+          ]
+        },
+        "notes": [
+          "supported Aggregate values are sum, avg, max, min, count, and distinct_count",
+          "unsupported aggregate names fail local body validation before the request is sent"
+        ]
+      }
+    ]
+  },
   "user.row.bulk-update": {
     "command": [
       "row",