@carthooks/arcubase-cli 0.1.2 → 0.1.3

package/sdk-dist/docs/runtime-reference/row-crud.md

@@ -0,0 +1,186 @@
+# Row CRUD
+
+Use this page for direct row operations with `arcubase`.
+
+## Insert a row
+
+Command:
+
+```bash
+arcubase workflow insert-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file insert.json
+```
+
+Minimal `insert.json`:
+
+```json
+{
+  "fields": {
+    "1001": "ORD-001",
+    "1002": 12,
+    "1003": 1
+  }
+}
+```
+
+Rules:
+
+- use numeric field ids as JSON object keys
+- values must match the saved schema
+
+Success result:
+
+```json
+{
+  "data": 4000000046
+}
+```
+
+The returned value is the new `row_id`.
+
+## Query rows
+
+Command:
+
+```bash
+arcubase workflow query-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file query.json
+```
+
+Minimal `query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0
+}
+```
+
+Rules:
+
+- do not use `viewMode`
+- if you need the view selector, use `view_mode`
+- if you need archived view, also pass `--query-file`
+
+Typical row shape:
+
+```json
+{
+  "id": 4000000046,
+  "fields": {
+    "1001": "ORD-001",
+    "1002": 99,
+    "1003": 1
+  }
+}
+```
+
+## Read one row
+
+Command:
+
+```bash
+arcubase workflow get-entity-row \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --row-id <row_id>
+```
+
+Use this when you already know the row id and want the full record payload.
+
+## Update a row
+
+Command:
+
+```bash
+arcubase workflow update-entity-row \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --row-id <row_id> \
+  --body-file update.json
+```
+
+Minimal `update.json`:
+
+```json
+{
+  "data": {
+    "1002": 99
+  },
+  "changed_fields": [1002]
+}
+```
+
+Rules:
+
+- use `data`, not `fields`
+- `changed_fields` is required
+- every id in `changed_fields` must also appear in `data`
+- use numeric field ids as JSON object keys
+
+Success result:
+
+```json
+{
+  "data": true
+}
+```
+
+The update command returns `true`, not the updated row body.
+
+## Delete rows
+
+Command:
+
+```bash
+arcubase workflow delete-entity-row \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file delete.json
+```
+
+Minimal `delete.json`:
+
+```json
+{
+  "selection": {
+    "type": "ids",
+    "ids": [4000000046],
+    "length": 1
+  }
+}
+```
+
+Rules:
+
+- use `selection.type = "ids"`
+- when `length` is provided, keep it equal to `ids.length`
+
+## Restore rows
+
+Command:
+
+```bash
+arcubase workflow restore-entity-row \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file restore.json
+```
+
+Minimal `restore.json`:
+
+```json
+{
+  "selection": {
+    "type": "ids",
+    "ids": [4000000046],
+    "length": 1
+  }
+}
+```
+
+The same `selection` rules apply as delete.

package/sdk-dist/docs/runtime-reference/search-and-bulk-actions.md

@@ -0,0 +1,494 @@
+# Search And Bulk Actions
+
+Use this page for:
+
+- search
+- selection actions
+- archived queries
+- bulk update
+- selection tags
+- batch operator
+
+## Main query command
+
+Use:
+
+```bash
+arcubase workflow query-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file query.json
+```
+
+For extra query-string parameters, also use:
+
+```bash
+--query-file query-extra.json
+```
+
+## Text search
+
+`query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "search": {
+    "text_search": "ORD-3001"
+  }
+}
+```
+
+This is the current success path for free-text search.
+
+## Sorts
+
+`query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "sorts": [
+    { "column": ":1002", "order": "desc" }
+  ]
+}
+```
+
+Rules:
+
+- use field columns as `:<field_id>`
+- `order` should be `asc` or `desc`
+
+## Deleted view
+
+`query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "view_mode": "deleted"
+}
+```
+
+## Archived view
+
+Archived view requires both:
+
+- `--body-file archived-body.json`
+- `--query-file archived-query.json`
+
+Command:
+
+```bash
+arcubase workflow query-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --query-file archived-query.json \
+  --body-file archived-body.json
+```
+
+`archived-body.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "view_mode": "archived"
+}
+```
+
+`archived-query.json`:
+
+```json
+{
+  "ym": "202605"
+}
+```
+
+Rules:
+
+- `ym` is required
+- `ym` format is `YYYYMM`
+
+## Selection with explicit ids
+
+Use this when you already know the row ids.
+
+Selection fragment:
+
+```json
+{
+  "selection": {
+    "type": "ids",
+    "ids": [4000000111],
+    "length": 1
+  }
+}
+```
+
+Rules:
+
+- `length` should match `ids.length`
+- this is the safest path for delete, restore, tags, and targeted bulk actions
+
+## Selection with conditions
+
+Use this when the action should apply to the current filtered result set.
+
+This shape is **not** the same as `query.json.search`.
+
+Use route-query style keys inside `selection.condition`:
+
+- `q`
+- `tab`
+- `filter_:<field_id_or_prop>`
+
+Example with `q`:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 1,
+    "condition": {
+      "q": "A-bts3",
+      "selectAll": true
+    },
+    "sorts": [
+      { "column": ":1002", "order": "desc" }
+    ]
+  }
+}
+```
+
+Example with `filter_:...`:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 1,
+    "condition": {
+      "filter_:1001": "%7B%22is%22%3A%22A-bts2%22%7D",
+      "selectAll": true
+    },
+    "sorts": [
+      { "column": ":1002", "order": "desc" }
+    ]
+  }
+}
+```
+
+Rules:
+
+- `condition.selectAll` must be `true`
+- do not use `text_search` inside `selection.condition`
+- `filter_:...` values should be URL-encoded JSON strings
+- keep `length` equal to the intended matched count
+- include `sorts` when your selection came from a sorted list view
+
+## Query selected rows
+
+Command:
+
+```bash
+arcubase workflow query-entity-selection \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --action query \
+  --body-file query-selection.json
+```
+
+Working `query-selection.json` with ids:
+
+```json
+{
+  "selection": {
+    "type": "ids",
+    "ids": [4000000127],
+    "length": 1
+  }
+}
+```
+
+Working `query-selection.json` with all:
+
+```json
+{
+  "selection": {
+    "type": "all"
+  }
+}
+```
+
+Rules:
+
+- use `selection.type = "ids"` when you know exact row ids
+- use `selection.type = "all"` to query the current result set
+- do not use `selection.type = "condition"` for `--action query`
+
+## Archive by selection
+
+Command:
+
+```bash
+arcubase workflow query-entity-selection \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --action archive \
+  --body-file archive-selection.json
+```
+
+Rules:
+
+- use `ids`, or `condition` with `selectAll: true` plus at least one real filter key
+- do not use `selection.type = "all"`
+- do not use `condition` with only `selectAll: true`
+
+## Batch print selection
+
+Command:
+
+```bash
+arcubase workflow query-entity-selection \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --action batch_print \
+  --body-file batch-print-selection.json
+```
+
+Working shape:
+
+```json
+{
+  "policy_id": "",
+  "selection": {
+    "type": "ids",
+    "ids": [4000000127],
+    "length": 1
+  },
+  "offset": 0,
+  "limit": 10
+}
+```
+
+## Bulk update
+
+Command:
+
+```bash
+arcubase entity update-entity-bulk \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file bulk-update.json
+```
+
+Working `bulk-update.json` with ids:
+
+```json
+{
+  "selection": {
+    "type": "ids",
+    "ids": [4000000104],
+    "length": 1
+  },
+  "fields": [
+    {
+      "id": 1002,
+      "action": {
+        "type": "number_add",
+        "number_add": 10
+      }
+    }
+  ]
+}
+```
+
+Working `bulk-update.json` with conditions:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 1,
+    "condition": {
+      "q": "A-bts3",
+      "selectAll": true
+    },
+    "sorts": [
+      { "column": ":1002", "order": "desc" }
+    ]
+  },
+  "fields": [
+    {
+      "id": 1002,
+      "action": {
+        "type": "number_add",
+        "number_add": 2
+      }
+    }
+  ]
+}
+```
+
+Working `bulk-update.json` for a select or status field:
+
+```json
+{
+  "selection": {
+    "type": "condition",
+    "length": 1,
+    "condition": {
+      "q": "SO-1001",
+      "selectAll": true
+    }
+  },
+  "fields": [
+    {
+      "id": 1015,
+      "action": {
+        "type": "set",
+        "value": "Confirmed"
+      }
+    }
+  ]
+}
+```
+
+Current reliable action types:
+
+- `set`
+- `text_replace`
+- `text_append`
+- `text_prepend`
+- `number_add`
+- `number_sub`
+- `number_mul`
+- `datetime_add`
+- `datetime_sub`
+- `datetime_now`
+- `formula`
+
+Rules:
+
+- use `type: set` when you want to assign a new scalar value directly
+- for `type: set`, send the new value as `action.value`
+- do not use `type: value`
+
+## Selection tags
+
+These commands use `arcubase-admin`.
+
+Get tags:
+
+```bash
+arcubase-admin entity-tags get-selection-tags \
+  --appId <app_id> \
+  --entityId <entity_id> \
+  --body-file get-tags.json
+```
+
+`get-tags.json`:
+
+```json
+{
+  "policy_id": "",
+  "selection": {
+    "type": "ids",
+    "ids": [4000000127],
+    "length": 1
+  }
+}
+```
+
+Add tags:
+
+```bash
+arcubase-admin entity-tags batch-add-entity-tags \
+  --appId <app_id> \
+  --entityId <entity_id> \
+  --body-file add-tags.json
+```
+
+`add-tags.json`:
+
+```json
+{
+  "policy_id": "",
+  "selection": {
+    "type": "ids",
+    "ids": [4000000127],
+    "length": 1
+  },
+  "tag_names": ["tag-a", "tag-b"]
+}
+```
+
+Remove tags:
+
+```bash
+arcubase-admin entity-tags batch-remove-entity-tags \
+  --appId <app_id> \
+  --entityId <entity_id> \
+  --body-file remove-tags.json
+```
+
+`remove-tags.json`:
+
+```json
+{
+  "policy_id": "",
+  "selection": {
+    "type": "ids",
+    "ids": [4000000127],
+    "length": 1
+  },
+  "tag_names": ["tag-a"]
+}
+```
+
+Rules:
+
+- for admin-mode local validation, `policy_id` can be `""`
+- these commands use the same `selection` rules as other selection actions
+- `tag_names` must be a non-empty string array
+
+## Invoke batch operator
+
+Command:
+
+```bash
+arcubase entity invoke-entity-batch-operator \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file invoke-batch-operator.json
+```
+
+Current writable shape:
+
+```json
+{
+  "id": "test-action-id",
+  "data": {
+    "action_id": "non-existent-action",
+    "policy_id": "",
+    "selection": {
+      "type": "ids",
+      "ids": [4000000127],
+      "length": 1
+    }
+  },
+  "params": {}
+}
+```
+
+Rules:
+
+- `id` is the frontend event id inside the custom action
+- `data.action_id` is the custom action id
+- `data.selection` is required
+- `params` is optional and should be an object
+- if the entity has no matching custom action or event, the server returns an upstream error