@carthooks/arcubase-cli 0.1.20 → 0.1.22

package/sdk-dist/api/admin/public-link.ts

@@ -0,0 +1,48 @@
+import { getDefaultClient } from '../../factory'
+import type {
+  EntityPublicLinkType,
+  PublicLinkConfigItemVO,
+  PublicLinkConfigReqVO,
+  PublicLinkConfigRespVO,
+  PublicRecordLinkRespVO
+} from '../../types/public-link'
+
+// @endpoint GET /api/apps/:app_id/entity/:entity_id/public-links
+// @controller PublicLink.ConfigList
+export async function getPublicLinkConfigs(
+  appId: string,
+  entityId: string
+): Promise<PublicLinkConfigRespVO> {
+  return getDefaultClient().get(`/apps/${appId}/entity/${entityId}/public-links`)
+}
+
+// @endpoint PUT /api/apps/:app_id/entity/:entity_id/public-links/:type
+// @controller PublicLink.ConfigSave
+export async function savePublicLinkConfig(
+  appId: string,
+  entityId: string,
+  type: EntityPublicLinkType,
+  data: PublicLinkConfigReqVO
+): Promise<PublicLinkConfigItemVO> {
+  return getDefaultClient().put(`/apps/${appId}/entity/${entityId}/public-links/${type}`, data)
+}
+
+// @endpoint POST /api/apps/:app_id/entity/:entity_id/public-links/:type/regenerate
+// @controller PublicLink.ConfigRegenerate
+export async function regeneratePublicLinkConfig(
+  appId: string,
+  entityId: string,
+  type: EntityPublicLinkType
+): Promise<PublicLinkConfigItemVO> {
+  return getDefaultClient().post(`/apps/${appId}/entity/${entityId}/public-links/${type}/regenerate`)
+}
+
+// @endpoint POST /api/apps/:app_id/entity/:entity_id/public-links/record/:row_id
+// @controller PublicLink.RecordLinkCreate
+export async function createPublicRecordLink(
+  appId: string,
+  entityId: string,
+  rowId: number | string
+): Promise<PublicRecordLinkRespVO> {
+  return getDefaultClient().post(`/apps/${appId}/entity/${entityId}/public-links/record/${rowId}`)
+}

package/sdk-dist/api/shared-link/form.ts

@@ -1,16 +1,19 @@
 import { getDefaultClient } from '../../factory'
 import type {
   SharedLinkInitRespVO,
+  SharedLinkPublicQueryReqVO,
+  SharedLinkPublicQueryRespVO,
   SharedLinkPushMobileUploadReqVO,
   SharedLinkPushMobileUploadRespVO,
   SharedLinkSubmissionSubmitReqVO,
   SharedLinkSubmissionSubmitRespVO
-} from '../../types/shared-link'
+} from '../../types'
 import type {
   EntityValidateUniqReqVO,
   EntityValidateUniqRespVO,
   EntityQueryRelationReqVO,
   EntityQueryRelationRespVO,
+  EntityQueryLinkToValuesReqVO,
   GetUploadTokenRespVO,
   UploadPreviewReqVO,
   UploadPreviewRespVO,
@@ -31,6 +34,36 @@ export async function querySharedLinkEntityRelation(
   return getDefaultClient().post(`/form/entity/${appId}/${entityId}/query-rel`, data)
 }
 
+// @endpoint POST /link/api/form/entity/:app_id/:entity_id/query-linkto-pick
+// @controller SharedLink.EntityQueryLinkToPick
+export async function querySharedLinkEntityLinkToPick(
+  appId: string,
+  entityId: string,
+  data: EntityQueryRelationReqVO
+): Promise<EntityQueryRelationRespVO> {
+  return getDefaultClient().post(`/form/entity/${appId}/${entityId}/query-linkto-pick`, data)
+}
+
+// @endpoint POST /link/api/form/entity/:app_id/:entity_id/query-linkto-values
+// @controller SharedLink.EntityQueryLinkToValues
+export async function querySharedLinkEntityLinkToValues(
+  appId: string,
+  entityId: string,
+  data: EntityQueryLinkToValuesReqVO
+): Promise<EntityQueryRelationRespVO> {
+  return getDefaultClient().post(`/form/entity/${appId}/${entityId}/query-linkto-values`, data)
+}
+
+// @endpoint POST /link/api/form/entity/:app_id/:entity_id/query-subform-rel
+// @controller SharedLink.EntityQuerySubformRelation
+export async function querySharedLinkEntitySubformRelation(
+  appId: string,
+  entityId: string,
+  data: any
+): Promise<any> {
+  return getDefaultClient().post(`/form/entity/${appId}/${entityId}/query-subform-rel`, data)
+}
+
 // @endpoint GET /link/api/form/dataset/:id/:node_id
 // @controller SharedLink.GetDataset
 export async function getSharedLinkDataset(
@@ -52,6 +85,14 @@ export async function initSharedLink(): Promise<SharedLinkInitRespVO> {
   return getDefaultClient().post('/init')
 }
 
+// @endpoint POST /link/api/query
+// @controller SharedLink.PublicQuery
+export async function querySharedLinkPublic(
+  data: SharedLinkPublicQueryReqVO
+): Promise<SharedLinkPublicQueryRespVO> {
+  return getDefaultClient().post('/query', data)
+}
+
 // @endpoint POST /link/api/form/upload/mobile-upload
 // @controller SharedLink.MobileUpload
 export async function uploadSharedLinkMobile(

package/sdk-dist/api/user/index.ts

@@ -6,7 +6,6 @@ export * from './profile'
 export * from './common'
 export * from './workflow'
 export * from './kiosk'
-export * from './copilot'
 export * from './flow'
 export * from './context'
 export * from './global-action'

package/sdk-dist/docs/runtime-reference/access-rule.md

@@ -112,6 +112,25 @@ Rules:
 - Multiple scope items are OR: any matching user, department membership, or actor membership can use the ingress.
 - Department scope includes child departments because Arcubase matches the user's department path.
 
+## Bulk Apply Across Tables
+
+Use this when assigning or updating many access rules for one app. This is the single path for matrix-style permission setup. Do not loop `access-rule list` and `access-rule update` for every table/rule.
+
+```bash
+arcubase-admin access-rule bulk-apply \
+  --app-id 2188893436 \
+  --body-json '{"mode":"upsert_by_name","items":[{"table_id":2188893443,"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"department","id":2188881201}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"condition":{"mode":"and","conditions":[{"column":"creator","operator":"$eq","value":"[[current_user]]","value_from":0,"value_relation":""}]}},"list_options":{}}},{"table_id":2188893444,"name":"Sales readonly","enabled":true,"type":"form","options":{"user_scope":[{"type":"actor","id":2188883301}],"policy":{"key":"custom","actions":["view"],"all_fields_read":true,"all_fields_write":false},"list_options":{}}}]}'
+```
+
+Rules:
+
+- `bulk-apply` runs in one backend transaction.
+- `mode:"update_existing"` requires every item to include `rule_id`.
+- `mode:"upsert_by_name"` requires every item to include `name` and must not include `rule_id`.
+- Each item must include `table_id` and the full canonical `options` object.
+- Numeric IDs passed as strings are normalized by the CLI for `table_id`, `rule_id`, and `options.user_scope[].id`.
+- Use `dry_run:true` to preview the exact operations without writing.
+
 ## Verify
 
 ```bash

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

@@ -0,0 +1,15 @@
+# Dashboard
+
+Use `arcubase dashboard get` and `arcubase dashboard widgets` to read dashboards as a tenant user.
+
+Use `arcubase-admin dashboard list`, `arcubase-admin dashboard create`, `arcubase-admin dashboard get-options`, `arcubase-admin dashboard update-options`, `arcubase-admin dashboard update-layout`, and `arcubase-admin dashboard rename` to manage dashboards as an admin.
+
+Dashboard title updates use body `{"name":"..."}`.
+
+Dashboard layout updates use a top-level JSON array of layout positions, not an object wrapper. Example:
+
+```json
+[{"id":2188892001,"x":0,"y":0,"w":12,"h":6}]
+```
+
+Dashboard delete and clone are not exposed in the CLI surface until backend routes are registered.

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/access-rule/bulk-apply.json

@@ -0,0 +1,105 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "bulk-apply"],
+  "examples": [
+    {
+      "title": "upsert permission matrix by rule name in one transaction",
+      "body": {
+        "mode": "upsert_by_name",
+        "items": [
+          {
+            "table_id": 2188893443,
+            "name": "Customer archive - sales owns rows",
+            "enabled": true,
+            "type": "form",
+            "options": {
+              "user_scope": [{"type": "department", "id": 2188881201}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view", "add", "edit"],
+                "all_fields_read": true,
+                "all_fields_write": true,
+                "condition": {
+                  "mode": "and",
+                  "conditions": [
+                    {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""}
+                  ]
+                }
+              },
+              "list_options": {}
+            }
+          },
+          {
+            "table_id": 2188893444,
+            "name": "Lead review - manager queue",
+            "enabled": true,
+            "type": "form",
+            "options": {
+              "user_scope": [{"type": "actor", "id": 2188883301}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view", "edit"],
+                "all_fields_read": true,
+                "all_fields_write": true,
+                "condition": {
+                  "mode": "and",
+                  "conditions": [
+                    {"column": ":1004", "operator": "$eq", "value": "pending", "value_from": 0, "value_relation": ""},
+                    {
+                      "column": "",
+                      "operator": "",
+                      "value": null,
+                      "value_from": 0,
+                      "value_relation": "",
+                      "subset": {
+                        "mode": "or",
+                        "conditions": [
+                          {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""},
+                          {"column": ":1005", "operator": "$eq", "value": "high", "value_from": 0, "value_relation": ""}
+                        ]
+                      }
+                    }
+                  ]
+                }
+              },
+              "list_options": {}
+            }
+          }
+        ]
+      },
+      "notes": [
+        "mode upsert_by_name is for idempotent setup; rule names must be unique within each table",
+        "department, actor, and specific user scopes all use options.user_scope",
+        "row-owner isolation uses [[current_user]] in policy.condition"
+      ]
+    },
+    {
+      "title": "preview updates for existing rule ids",
+      "body": {
+        "mode": "update_existing",
+        "dry_run": true,
+        "items": [
+          {
+            "table_id": 2188893443,
+            "rule_id": 2188893557,
+            "enabled": true,
+            "options": {
+              "user_scope": [{"type": "user", "id": 2188889901}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view"],
+                "all_fields_read": true,
+                "all_fields_write": false
+              },
+              "list_options": {}
+            }
+          }
+        ]
+      },
+      "notes": [
+        "dry_run true returns the planned operations without writing",
+        "update_existing requires rule_id on every item"
+      ]
+    }
+  ]
+}

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,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.