@carthooks/arcubase-cli 0.1.21 → 0.1.23

package/sdk-dist/docs/runtime-reference/dev-sdk-gen.md

@@ -0,0 +1,41 @@
+# Dev SDK Gen
+
+Use `arcubase-admin dev sdk-gen` to generate typed TypeScript source for a Web project.
+
+```bash
+arcubase-admin dev sdk-gen \
+  --app-id <app_id> \
+  --out src/arcubase
+```
+
+The command reads the app schema from Arcubase through the normal `arcubase-admin` runtime auth and writes project-local source files under `--out`.
+
+Generated code is key based. Application code uses stable `field.key` names, while generated runtime code converts those keys to internal numeric field ids.
+If a field is missing `field.key`, the command initializes it through `PUT /api/apps/:app_id/entity/:entity_id/custom-keys` with a stable `field<id>` fallback before generation.
+
+```ts
+import { createArcubaseSdk } from './arcubase'
+
+const sdk = createArcubaseSdk({
+  baseURL: 'https://team.example.arcubase.co/api',
+  accessToken,
+  refreshToken,
+})
+
+await sdk.story.create({
+  story: 'Once upon a time',
+})
+
+await sdk.story.update(rowId, {
+  story: 'Updated story',
+})
+```
+
+Rules:
+
+- missing `field.key` values are initialized through admin auth as `field<id>`
+- existing `field.key` values must be stable unique TypeScript identifiers
+- `field.key` is a developer API contract and should not track display labels
+- entity property names use `entity.key` when available, otherwise a stable `entity<id>` fallback
+- row create/update/query code should use generated types, not raw field ids
+- rerun the command after schema changes and commit the regenerated source with the Web project

package/sdk-dist/docs/runtime-reference/help-examples/admin/dashboard/update-layout.json

@@ -0,0 +1,16 @@
+{
+  "scope": "admin",
+  "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\":[...]}"
+      ]
+    }
+  ]
+}

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,66 @@
+{
+  "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"
+      ]
+    },
+    {
+      "title": "preview filtered distinct_count grouped by source",
+      "body": {
+        "dataSource": 2188891001,
+        "dataSourceType": "entity",
+        "dimensions": [
+          {"IsField": true, "FieldID": 1004, "Name": "Source"}
+        ],
+        "conditions": {
+          "mode": "and",
+          "conditions": [
+            {"column": ":1006", "operator": "$eq", "value": "yes"}
+          ]
+        },
+        "measures": [
+          {"FieldID": 1002, "Aggregate": "distinct_count", "Name": "Distinct Customers"}
+        ]
+      },
+      "notes": [
+        "use conditions, not filters, for chart data filtering",
+        "for saved charts put the same condition set under options.charts.conditions",
+        "do not remove the condition and hand-calculate filtered statistics from row query results"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/widget/update-ingress-options.json

@@ -0,0 +1,21 @@
+{
+  "scope": "admin",
+  "command": ["widget", "update-ingress-options"],
+  "examples": [
+    {
+      "title": "adjust an ingress list widget display configuration",
+      "body": {
+        "options": {
+          "cond_follow": true,
+          "cond_follow_tab": true,
+          "cond_follow_cols": [":1001", ":1002"]
+        }
+      },
+      "notes": [
+        "use this only for widgets created with options.ingress_id",
+        "do not use dashboard update-layout for ingress widgets",
+        "verify with widget get after updating ingress options"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,64 @@
+# 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`.
+
+Create ingress list widgets with `{"type":"list","options":{"ingress_id":<ingress_id>}}`, where `ingress_id` is the entry/access-rule id. Do not put `entity_id` at the top level or under `options` when creating a widget. After creation, adjust entry list display settings with `widget update-ingress-options`, then verify with `widget get`. Ingress widgets have `dashboard_id:0` and must not be placed with `dashboard update-layout`.
+
+If ingress/list display settings such as `ingress_id`, `list`, `default_cols`, or `page_size` are rejected by `widget update`, switch to `widget update-ingress-options`; do not retry `widget update` with empty options.
+
+```json
+{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}
+```
+
+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 conditions
+
+Use `conditions`, not `filters`, to filter dashboard chart statistics. The condition set shape is:
+
+```json
+{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]}
+```
+
+For saved widgets, place this under `options.charts.conditions`. For `widget preview-data`, place it at top level beside `dataSource`, `dimensions`, and `measures`.
+
+```json
+{"dataSource":2188891001,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":1004,"Name":"Source"}],"conditions":{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]},"measures":[{"FieldID":1002,"Aggregate":"distinct_count","Name":"Distinct Customers"}]}
+```
+
+Fastfail rule: if a chart statistic requires filtering and validation rejects a guessed key such as `filters`, retry with `conditions`. Do not remove the filter and then hand-calculate filtered statistics from row data.
+
+## 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,77 @@ export const userCommands = [
     ],
     "responseType": "GlobalActionEntryRespVO"
   },
+  {
+    "scope": "user",
+    "module": "app",
+    "functionName": "getAppDetail",
+    "commandPath": [
+      "app",
+      "get"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:id",
+    "pathParams": [
+      {
+        "param": "id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "UserAction.AppDetail",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "AppDetailRespVO"
+  },
+  {
+    "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 +1445,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",