flowbase-cli 0.1.8__tar.gz → 0.1.10__tar.gz

{flowbase_cli-0.1.8 → flowbase_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.8
+Version: 0.1.10
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
@@ -9,7 +9,7 @@ Description-Content-Type: text/markdown
 
 # FlowBase CLI
 
-`flowbase` is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
+`flowbase` is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, approval flows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
 
 ## 1. Install and connect
 
@@ -47,7 +47,7 @@ Most commands run on every Host; `roles` is production-only and `changes commit/
 
 ### 3.1 Metadata vs records
 
-- **Metadata** (`metadata` scope): apps, objects, fields, views, pages, workflows, dashboards, roles, versions.
+- **Metadata** (`metadata` scope): apps, objects, fields, views, pages, workflows, approvals, dashboards, roles, versions.
 - **Business records** (`records` scope): rows inside an object.
 
 Metadata changes are **drafts** against the current environment's configuration repository. They do not affect the running front-end until they are committed and released.
@@ -77,9 +77,11 @@ flowbase
 │                   add-dashboards | remove-dashboard | set-dashboard-group | reorder-members
 ├── groups          create | reorder | update | delete    App groups (under an app)
 ├── objects         list | get | create | update | delete | restore
+│                   cli-edit-policy get | update
 ├── fields          create | update | delete | restore    Fields under an object
 ├── views           list | create | update | reorder | set-enabled | delete
 ├── workflows       list | get | create | update | reorder | set-enabled | delete | executions
+├── approvals       list | get | create | update | reorder | set-enabled | delete
 ├── pages           list | options | get | create | update | set-default | delete | restore
 ├── dashboards      list | get | create | update | copy | delete
 ├── changes         commit | release | direct-release
@@ -89,7 +91,7 @@ flowbase
 └── roles           list | options | get | create | update | delete   (production only)
 ```
 
-Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`.
+Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`. They may appear **before or after** the subcommand (`flowbase apps list --no-pretty` is valid).
 
 ## 5. Discovering request bodies
 
@@ -110,18 +112,24 @@ Complex bodies reference closed sets that are not guessable from examples. Query
 
 ```bash
 flowbase docs catalogs                    # list available catalogs
-flowbase docs catalogs field-types        # field type names + allowed constraints
+flowbase docs catalogs authoring          # required fields, draftRevision sources, common mistakes
+flowbase docs catalogs field-types        # types, constraints, filter operators, record values, create examples
+flowbase docs catalogs view-filters       # view filter operators and value shapes (not page-rules)
+flowbase docs catalogs record-values      # how to write records.values by field type
 flowbase docs catalogs workflow-nodes     # node types with in/out edge rules
 flowbase docs catalogs permissions        # function permission points + data scopes
 flowbase docs catalogs dashboard-filters  # filter types + date-range presets
-flowbase docs catalogs page-components    # page region component kinds (field / relatedList)
+flowbase docs catalogs page-components    # Page component shapes, placement, fields, and enums
+flowbase docs catalogs page-rules         # Page condition operators and action shapes
 flowbase docs catalogs id-prefixes        # resource ID prefix meanings
 flowbase docs catalogs icons              # icon guidance + examples
 ```
 
+Read `authoring` before composing any write. It lists the mistakes that most often make generated commands fail: missing `description`/`type`, select options without `id`+`lifecycle`, `defaultValue: null` (omit the key instead), boolean view filters using `eq`, `records.list` being a column projection, `pages.list.pages` being a page count, and `objects.get` not returning `draftRevision`.
+
 ### The read → modify → write loop
 
-Most `update` commands replace a **full snapshot** and accept an optional `baseRevision` for optimistic locking. The safe pattern is:
+Most `update` commands replace a **full snapshot** and accept an optional `baseRevision` for optimistic locking. Check the relevant offline catalog for its exact update envelope and read-only response fields. The safe pattern is:
 
 ```bash
 flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
@@ -129,16 +137,20 @@ flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
 flowbase dashboards update dsh_xxx --json-file current.json
 ```
 
-Do not compose update bodies from scratch when an existing resource exists — `get` returns the server-valid shape, including `baseRevision`.
+Do not compose update bodies from scratch when an existing resource exists. Start from `get`, then convert its read projection to the update envelope documented by the relevant catalog.
 
 ## 6. Recipes
 
 ### 6.1 Create an object with a field and a record
 
 ```bash
-flowbase objects create --label Customer --key customer --description "Customer records"
-flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","permission":"required"}'
+flowbase docs catalogs authoring
+flowbase docs catalogs field-types
+flowbase objects create --json '{"label":"Customer","key":"customer","description":"Customer records","icon":"IconUsers"}'
+flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","typeVersion":"v1","permission":"required","constraints":{"maxLength":120}}'
 flowbase records create obj_xxx --json '{"values":{"name":"Acme Corp"}}'
+flowbase objects cli-edit-policy get obj_xxx
+flowbase objects cli-edit-policy update obj_xxx --json '{"baseRevision":4,"policies":{"fld_xxx":"user_approval"}}' --yes
 ```
 
 Record `values` keys are **field keys** (`name`), not internal IDs (`fld_...`). IDs are `obj_`/`fld_`/`dsh_`/`wfl_`/`pag_`/`reg_`/`cmp_`-prefixed; see `docs catalogs id-prefixes`.
@@ -168,34 +180,60 @@ flowbase changes direct-release --message "Fix customer field" --yes
 
 `direct-release` always runs a server-side preflight, prints the current version, diff summary, checks and risk, and binds a one-time confirmation token. `--yes` accepts that reviewed result; it never skips validation.
 
-### 6.4 Workflows and pages
+On production, `records.*` sees **released** metadata only. Creating records on a brand-new object before `direct-release` returns `404 内容不存在或已被删除`. Finish metadata, release, then seed.
+
+### 6.4 Workflows, approvals, and pages
 
 A workflow graph must satisfy structural rules: exactly one `trigger` node, at least one `end` node, a DAG, and valid per-type edges. See `docs catalogs workflow-nodes` before composing `nodes`/`edges`.
 
+Workflow conditions use `fieldId` for current-object fields and add `relationFieldId` for a one-hop related field. Field-value references use `valueRef` plus optional `valueRefRelationFieldId`. An `updateRelated` node selects the target record with its required `relationFieldId`; its assignment `fieldId` values belong to that related object. Use `workflows list` to retrieve the current object fields and the available `relations` with target fields.
+
+Approval flow graphs are separate metadata: exactly one `trigger`, at least one `approval` node, both `approvedEnd` and `rejectedEnd`, and dual outcome edges from each approval node. Employee task decisions are not available via API key / CLI. See `docs catalogs approval-nodes`.
+
 ```bash
 flowbase docs catalogs workflow-nodes
 flowbase workflows create obj_xxx --json '{"label":"Set owner","enabled":true,"trigger":{"event":"create","match":"all","conditions":[]},"nodes":[],"edges":[]}'
 flowbase workflows update obj_xxx wfl_xxx --json-file workflow.json
 flowbase workflows executions obj_xxx wfl_xxx --result failure
 
-flowbase docs catalogs page-components                  # field + relatedList keys
+flowbase docs catalogs approval-nodes
+flowbase docs example approvals.create --output approval.json
+flowbase approvals create obj_xxx --json-file approval.json
+flowbase approvals set-enabled obj_xxx apr_xxx --base-revision 4 --enabled --yes
+
+flowbase docs catalogs page-components                  # all component shapes and placement rules
+flowbase docs catalogs page-rules                       # conditions, operators, and actions
+flowbase pages options                                  # objects, fields, and lookup constraints
 flowbase docs example pages.create --output page.json   # create-page layout template
 flowbase pages create --json-file page.json
 flowbase pages set-default pag_xxx --base-revision 4 --yes
 
-# Detail pages may embed relatedList components (reverse lookup lists).
-flowbase pages get pag_xxx > page.json                  # prefer get → edit → update
-# or: flowbase docs example pages.update --output page.json
+# Detail pages support detailSummary, stageBar, tabs, relatedSummary,
+# attachmentCard, noticeBlock, relatedList, and approval components.
+# A placed field uses sourcePath=[] for the Page object, or 1-2
+# {relationFieldId,targetObjectId} hops for a related object field.
+# Component visibility uses a page-rules setComponentVisibility action
+# targeting the stable cmp_ ID returned by pages get.
+# Save and read back a newly added component before adding a rule for it.
+flowbase pages get pag_xxx > page-read.json
+# Build page.json as {baseRevision: page-read.draftRevision, page: page-read.page},
+# then remove the read-only Page keys listed by page-components.
+# Or start from the complete offline example:
+flowbase docs example pages.update --output page.json
 flowbase pages update pag_xxx --json-file page.json
 ```
 
 ### 6.5 Records and attachments
 
+`records.list` is a **column projection** of the current view (often only the title field). Use `records.get` for the full `values` object. `values` keys are field keys; select/lookup values are option/record IDs.
+
 ```bash
 flowbase records list obj_xxx --page 1
 flowbase records get obj_xxx rec_xxx
+flowbase docs catalogs record-values
+flowbase records create obj_xxx --json '{"values":{"name":"Ada","status":"opt_xxx","class":"rec_xxx"}}'
 flowbase records upload-attachment obj_xxx fld_xxx ./contract.pdf
-flowbase records update obj_xxx rec_xxx --json '{"values":{"fld_contract":["att_xxx"]}}'
+flowbase records update obj_xxx rec_xxx --json '{"values":{"attachments":["att_xxx"]}}'
 flowbase records download-attachment obj_xxx rec_xxx att_xxx --output ./contract.pdf
 ```
 

{flowbase_cli-0.1.8 → flowbase_cli-0.1.10}/README.md

@@ -1,6 +1,6 @@
 # FlowBase CLI
 
-`flowbase` is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
+`flowbase` is the official command line client for the FlowBase OpenAPI. It manages apps, objects, fields, views, custom pages, workflows, approval flows, dashboards, business records, roles, and configuration versions across the three FlowBase environments.
 
 ## 1. Install and connect
 
@@ -38,7 +38,7 @@ Most commands run on every Host; `roles` is production-only and `changes commit/
 
 ### 3.1 Metadata vs records
 
-- **Metadata** (`metadata` scope): apps, objects, fields, views, pages, workflows, dashboards, roles, versions.
+- **Metadata** (`metadata` scope): apps, objects, fields, views, pages, workflows, approvals, dashboards, roles, versions.
 - **Business records** (`records` scope): rows inside an object.
 
 Metadata changes are **drafts** against the current environment's configuration repository. They do not affect the running front-end until they are committed and released.
@@ -68,9 +68,11 @@ flowbase
 │                   add-dashboards | remove-dashboard | set-dashboard-group | reorder-members
 ├── groups          create | reorder | update | delete    App groups (under an app)
 ├── objects         list | get | create | update | delete | restore
+│                   cli-edit-policy get | update
 ├── fields          create | update | delete | restore    Fields under an object
 ├── views           list | create | update | reorder | set-enabled | delete
 ├── workflows       list | get | create | update | reorder | set-enabled | delete | executions
+├── approvals       list | get | create | update | reorder | set-enabled | delete
 ├── pages           list | options | get | create | update | set-default | delete | restore
 ├── dashboards      list | get | create | update | copy | delete
 ├── changes         commit | release | direct-release
@@ -80,7 +82,7 @@ flowbase
 └── roles           list | options | get | create | update | delete   (production only)
 ```
 
-Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`.
+Global flags: `--host`, `--api-key`, `--pretty`/`--no-pretty`, `--raw`. They may appear **before or after** the subcommand (`flowbase apps list --no-pretty` is valid).
 
 ## 5. Discovering request bodies
 
@@ -101,18 +103,24 @@ Complex bodies reference closed sets that are not guessable from examples. Query
 
 ```bash
 flowbase docs catalogs                    # list available catalogs
-flowbase docs catalogs field-types        # field type names + allowed constraints
+flowbase docs catalogs authoring          # required fields, draftRevision sources, common mistakes
+flowbase docs catalogs field-types        # types, constraints, filter operators, record values, create examples
+flowbase docs catalogs view-filters       # view filter operators and value shapes (not page-rules)
+flowbase docs catalogs record-values      # how to write records.values by field type
 flowbase docs catalogs workflow-nodes     # node types with in/out edge rules
 flowbase docs catalogs permissions        # function permission points + data scopes
 flowbase docs catalogs dashboard-filters  # filter types + date-range presets
-flowbase docs catalogs page-components    # page region component kinds (field / relatedList)
+flowbase docs catalogs page-components    # Page component shapes, placement, fields, and enums
+flowbase docs catalogs page-rules         # Page condition operators and action shapes
 flowbase docs catalogs id-prefixes        # resource ID prefix meanings
 flowbase docs catalogs icons              # icon guidance + examples
 ```
 
+Read `authoring` before composing any write. It lists the mistakes that most often make generated commands fail: missing `description`/`type`, select options without `id`+`lifecycle`, `defaultValue: null` (omit the key instead), boolean view filters using `eq`, `records.list` being a column projection, `pages.list.pages` being a page count, and `objects.get` not returning `draftRevision`.
+
 ### The read → modify → write loop
 
-Most `update` commands replace a **full snapshot** and accept an optional `baseRevision` for optimistic locking. The safe pattern is:
+Most `update` commands replace a **full snapshot** and accept an optional `baseRevision` for optimistic locking. Check the relevant offline catalog for its exact update envelope and read-only response fields. The safe pattern is:
 
 ```bash
 flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
@@ -120,16 +128,20 @@ flowbase dashboards get dsh_xxx > current.json      # authoritative snapshot
 flowbase dashboards update dsh_xxx --json-file current.json
 ```
 
-Do not compose update bodies from scratch when an existing resource exists — `get` returns the server-valid shape, including `baseRevision`.
+Do not compose update bodies from scratch when an existing resource exists. Start from `get`, then convert its read projection to the update envelope documented by the relevant catalog.
 
 ## 6. Recipes
 
 ### 6.1 Create an object with a field and a record
 
 ```bash
-flowbase objects create --label Customer --key customer --description "Customer records"
-flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","permission":"required"}'
+flowbase docs catalogs authoring
+flowbase docs catalogs field-types
+flowbase objects create --json '{"label":"Customer","key":"customer","description":"Customer records","icon":"IconUsers"}'
+flowbase fields create obj_xxx --json '{"label":"Name","key":"name","description":"Customer name","type":"text.singleLine","typeVersion":"v1","permission":"required","constraints":{"maxLength":120}}'
 flowbase records create obj_xxx --json '{"values":{"name":"Acme Corp"}}'
+flowbase objects cli-edit-policy get obj_xxx
+flowbase objects cli-edit-policy update obj_xxx --json '{"baseRevision":4,"policies":{"fld_xxx":"user_approval"}}' --yes
 ```
 
 Record `values` keys are **field keys** (`name`), not internal IDs (`fld_...`). IDs are `obj_`/`fld_`/`dsh_`/`wfl_`/`pag_`/`reg_`/`cmp_`-prefixed; see `docs catalogs id-prefixes`.
@@ -159,34 +171,60 @@ flowbase changes direct-release --message "Fix customer field" --yes
 
 `direct-release` always runs a server-side preflight, prints the current version, diff summary, checks and risk, and binds a one-time confirmation token. `--yes` accepts that reviewed result; it never skips validation.
 
-### 6.4 Workflows and pages
+On production, `records.*` sees **released** metadata only. Creating records on a brand-new object before `direct-release` returns `404 内容不存在或已被删除`. Finish metadata, release, then seed.
+
+### 6.4 Workflows, approvals, and pages
 
 A workflow graph must satisfy structural rules: exactly one `trigger` node, at least one `end` node, a DAG, and valid per-type edges. See `docs catalogs workflow-nodes` before composing `nodes`/`edges`.
 
+Workflow conditions use `fieldId` for current-object fields and add `relationFieldId` for a one-hop related field. Field-value references use `valueRef` plus optional `valueRefRelationFieldId`. An `updateRelated` node selects the target record with its required `relationFieldId`; its assignment `fieldId` values belong to that related object. Use `workflows list` to retrieve the current object fields and the available `relations` with target fields.
+
+Approval flow graphs are separate metadata: exactly one `trigger`, at least one `approval` node, both `approvedEnd` and `rejectedEnd`, and dual outcome edges from each approval node. Employee task decisions are not available via API key / CLI. See `docs catalogs approval-nodes`.
+
 ```bash
 flowbase docs catalogs workflow-nodes
 flowbase workflows create obj_xxx --json '{"label":"Set owner","enabled":true,"trigger":{"event":"create","match":"all","conditions":[]},"nodes":[],"edges":[]}'
 flowbase workflows update obj_xxx wfl_xxx --json-file workflow.json
 flowbase workflows executions obj_xxx wfl_xxx --result failure
 
-flowbase docs catalogs page-components                  # field + relatedList keys
+flowbase docs catalogs approval-nodes
+flowbase docs example approvals.create --output approval.json
+flowbase approvals create obj_xxx --json-file approval.json
+flowbase approvals set-enabled obj_xxx apr_xxx --base-revision 4 --enabled --yes
+
+flowbase docs catalogs page-components                  # all component shapes and placement rules
+flowbase docs catalogs page-rules                       # conditions, operators, and actions
+flowbase pages options                                  # objects, fields, and lookup constraints
 flowbase docs example pages.create --output page.json   # create-page layout template
 flowbase pages create --json-file page.json
 flowbase pages set-default pag_xxx --base-revision 4 --yes
 
-# Detail pages may embed relatedList components (reverse lookup lists).
-flowbase pages get pag_xxx > page.json                  # prefer get → edit → update
-# or: flowbase docs example pages.update --output page.json
+# Detail pages support detailSummary, stageBar, tabs, relatedSummary,
+# attachmentCard, noticeBlock, relatedList, and approval components.
+# A placed field uses sourcePath=[] for the Page object, or 1-2
+# {relationFieldId,targetObjectId} hops for a related object field.
+# Component visibility uses a page-rules setComponentVisibility action
+# targeting the stable cmp_ ID returned by pages get.
+# Save and read back a newly added component before adding a rule for it.
+flowbase pages get pag_xxx > page-read.json
+# Build page.json as {baseRevision: page-read.draftRevision, page: page-read.page},
+# then remove the read-only Page keys listed by page-components.
+# Or start from the complete offline example:
+flowbase docs example pages.update --output page.json
 flowbase pages update pag_xxx --json-file page.json
 ```
 
 ### 6.5 Records and attachments
 
+`records.list` is a **column projection** of the current view (often only the title field). Use `records.get` for the full `values` object. `values` keys are field keys; select/lookup values are option/record IDs.
+
 ```bash
 flowbase records list obj_xxx --page 1
 flowbase records get obj_xxx rec_xxx
+flowbase docs catalogs record-values
+flowbase records create obj_xxx --json '{"values":{"name":"Ada","status":"opt_xxx","class":"rec_xxx"}}'
 flowbase records upload-attachment obj_xxx fld_xxx ./contract.pdf
-flowbase records update obj_xxx rec_xxx --json '{"values":{"fld_contract":["att_xxx"]}}'
+flowbase records update obj_xxx rec_xxx --json '{"values":{"attachments":["att_xxx"]}}'
 flowbase records download-attachment obj_xxx rec_xxx att_xxx --output ./contract.pdf
 ```
 

{flowbase_cli-0.1.8 → flowbase_cli-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flowbase-cli"
-version = "0.1.8"
+version = "0.1.10"
 description = "Command line client for the FlowBase OpenAPI"
 readme = "README.md"
 requires-python = ">=3.11"

{flowbase_cli-0.1.8 → flowbase_cli-0.1.10}/src/flowbase_cli/__init__.py

@@ -1,3 +1,3 @@
 """FlowBase OpenAPI CLI."""
 
-__version__ = "0.1.8"
+__version__ = "0.1.10"