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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.9
+Version: 0.1.10
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
@@ -91,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
 
@@ -112,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 / approval)
+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
@@ -131,15 +137,17 @@ 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
@@ -172,10 +180,14 @@ 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.
 
+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
@@ -189,24 +201,39 @@ 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                  # field + relatedList + approval keys
+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 and at most one approval component.
-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.9 → flowbase_cli-0.1.10}/README.md

@@ -82,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
 
@@ -103,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 / approval)
+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
@@ -122,15 +128,17 @@ 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
@@ -163,10 +171,14 @@ 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.
 
+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
@@ -180,24 +192,39 @@ 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                  # field + relatedList + approval keys
+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 and at most one approval component.
-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.9 → flowbase_cli-0.1.10}/pyproject.toml

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

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

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