flowbase-cli 0.1.13__tar.gz → 0.1.14__tar.gz

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.13
+Version: 0.1.14
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
@@ -125,6 +125,7 @@ flowbase docs catalogs permissions        # function permission points + data sc
 flowbase docs catalogs dashboard-filters  # filter types + date-range presets
 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 forms              # custom form fields, rules, appearance, and settings
 flowbase docs catalogs id-prefixes        # resource ID prefix meanings
 flowbase docs catalogs icons              # icon guidance + examples
 ```

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/README.md

@@ -116,6 +116,7 @@ flowbase docs catalogs permissions        # function permission points + data sc
 flowbase docs catalogs dashboard-filters  # filter types + date-range presets
 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 forms              # custom form fields, rules, appearance, and settings
 flowbase docs catalogs id-prefixes        # resource ID prefix meanings
 flowbase docs catalogs icons              # icon guidance + examples
 ```

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/pyproject.toml

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

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/src/flowbase_cli/__init__.py

@@ -1,3 +1,3 @@
 """FlowBase OpenAPI CLI."""
 
-__version__ = "0.1.13"
+__version__ = "0.1.14"

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/src/flowbase_cli/endpoints.py

@@ -169,6 +169,26 @@ ENDPOINTS = (
              )),
     Endpoint("dashboards.copy", "flowbase_dashboards_copy", "POST", "/dashboards/{dashboard_id}/copy", "metadata:write", "Copy a dashboard (not added to any app).", "flowbase dashboards copy dsh_xxx"),
     Endpoint("dashboards.delete", "flowbase_dashboards_delete", "POST", "/dashboards/{dashboard_id}/delete", "metadata:write", "Logically delete a dashboard (also removed from all apps).", "flowbase dashboards delete dsh_xxx --yes", True),
+    Endpoint("forms.list", "flowbase_forms_list", "GET", "/forms", "metadata:read", "List custom forms with collection status.", "flowbase forms list"),
+    Endpoint("forms.get", "flowbase_forms_get", "GET", "/forms/{form_id}", "metadata:read", "Get a custom form definition and its placeable field options. Read docs catalogs forms before update.", "flowbase forms get frm_xxx"),
+    Endpoint("forms.create", "flowbase_forms_create", "POST", "/forms", "metadata:write", "Create a custom form draft; object-required fields are pre-added.", "flowbase forms create --label 'Website inquiry' --key website_inquiry --object-id obj_xxx",
+             request_body='{"label":"Website inquiry","key":"website_inquiry","objectId":"obj_xxx","description":""}'),
+    Endpoint("forms.update", "flowbase_forms_update", "PUT", "/forms/{form_id}", "metadata:write", "Update a custom form draft (full snapshot: fields, rules, appearance, settings). Read docs catalogs forms first.", "flowbase forms update frm_xxx --json-file form.json",
+             request_body=(
+                 '{"label":"Website inquiry","description":"","baseRevision":3,'
+                 '"fields":[{"fieldId":"fld_xxx","label":"","description":"","state":"required","prefill":false}],'
+                 '"rules":[],'
+                 '"appearance":{"title":"Website inquiry","description":"","logo":null,"cover":null,"themeColor":"#171717",'
+                 '"background":"gray","submitText":"提交","language":"zh-CN"},'
+                 '"settings":{"afterSubmit":"message","successTitle":"提交成功","successBody":"感谢你的填写",'
+                 '"allowResubmit":true,"redirectUrl":"","deadline":null,"limit":null}}'
+             )),
+    Endpoint("forms.copy", "flowbase_forms_copy", "POST", "/forms/{form_id}/copy", "metadata:write", "Copy a custom form (collection state is not copied).", "flowbase forms copy frm_xxx"),
+    Endpoint("forms.delete", "flowbase_forms_delete", "POST", "/forms/{form_id}/delete", "metadata:write", "Logically delete a custom form.", "flowbase forms delete frm_xxx --yes", True),
+    Endpoint("forms.share.get", "flowbase_forms_share_get", "GET", "/forms/{form_id}/share", "metadata:read", "Get the public link and collection state in this environment.", "flowbase forms share frm_xxx"),
+    Endpoint("forms.share.set-accepting", "flowbase_forms_share_set_accepting", "PUT", "/forms/{form_id}/share/accepting", "metadata:write", "Turn public collection on or off in this environment (immediate, not a draft change).", "flowbase forms set-accepting frm_xxx --on",
+             request_body='{"accepting":true}'),
+    Endpoint("forms.share.reset", "flowbase_forms_share_reset", "POST", "/forms/{form_id}/share/reset", "metadata:write", "Reset the public link; the old link stops working immediately.", "flowbase forms reset-link frm_xxx --yes", True),
     Endpoint("objects.list", "flowbase_objects_list", "GET", "/objects", "metadata:read", "List object metadata.", "flowbase objects list"),
     Endpoint("objects.get", "flowbase_objects_get", "GET", "/objects/{object_id}", "metadata:read", "Get object and field metadata.", "flowbase objects get obj_xxx"),
     Endpoint("objects.create", "flowbase_objects_create", "POST", "/objects", "metadata:write", "Create an object draft.", "flowbase objects create --json-file object.json",
@@ -563,7 +583,8 @@ ENDPOINT_BY_KEY = {endpoint.key: endpoint for endpoint in ENDPOINTS}
 
 # Closed-domain catalogs for offline authoring of complex request bodies.
 # Keep in sync with server registries (field types, workflow/approval node kinds,
-# permission points, dashboard filter presets, page component kinds).
+# permission points, dashboard filter presets, page component kinds, form
+# snapshot validation).
 # Icons intentionally reference the server file because the full Tabler set is large.
 _PERMISSIONS = ("required", "optional", "readonly", "hidden")
 _TEXT_FILTERS = ("eq", "neq", "contains", "not_contains", "is_empty", "is_not_empty")
@@ -802,7 +823,10 @@ AUTHORING = {
         ],
     },
     "documentationKeys": "docs list returns endpoint keys. Use apps.objects.add for apps add-objects; docs show includes the CLI example.",
-    "requiredUpdateFields": {"apps.update": ["label", "icon", "color"]},
+    "requiredUpdateFields": {
+        "apps.update": ["label", "icon", "color"],
+        "forms.update": ["label", "appearance", "settings"],
+    },
     "requiredCreateFields": {
         "objects.create": ["label", "key", "description"],
         "fields.create": ["label", "key", "description", "type"],
@@ -811,22 +835,27 @@ AUTHORING = {
         "pages.create": ["baseRevision", "page"],
         "records.create": ["values"],
         "print-templates.create": ["name", "html"],
+        "forms.create": ["label", "key", "objectId"],
     },
     "draftRevision": {
         "notReturnedBy": ["objects.get", "objects.list", "apps.get", "apps.list"],
         "returnedBy": [
             "views.list", "pages.list", "pages.get",
             "print-templates.list", "print-templates.get",
+            "forms.get",
             "every metadata write response (draftRevision)",
         ],
         "note": "Capture draftRevision from the last write or from views.list/pages.list/print-templates.list before writes.",
     },
     "readThenWrite": (
-        "For update of views/pages/dashboards/fields with constraints: get the snapshot, "
-        "edit it, set baseRevision from draftRevision. fields.update.constraints is a full replace; "
-        "sending {} wipes options. print-templates.update is partial: send only changed fields, "
-        "baseRevision, and baseUpdatedAt copied from updatedAt. Resending id, key, enabled, "
-        "updatedAt, or draftRevision is rejected."
+        "For update of views/pages/dashboards/forms/fields with constraints: get the snapshot, "
+        "edit it, set baseRevision from draftRevision. forms.update unwraps forms.get: send "
+        "label, description, fields, rules, appearance, settings, and baseRevision; omit the "
+        "form wrapper, id, key, objectId, updatedAt, and fieldOptions. Omitting fields or rules "
+        "clears them. fields.update.constraints is a full replace; sending {} wipes options. "
+        "print-templates.update is partial: send only changed fields, baseRevision, and "
+        "baseUpdatedAt copied from updatedAt. Resending id, key, enabled, updatedAt, or "
+        "draftRevision is rejected."
     ),
     "recordsNeedReleasedMetadata": (
         "On production, records.create/list/get use the released runtime, not the current draft. "
@@ -840,6 +869,7 @@ AUTHORING = {
         "dashboards.run": "{ok,output,error,logs,durationMs,cached,mode:draft-preview}; inspect ok and error.",
         "apps.create": "{appId,draftRevision}",
         "dashboards.create": "{dashboardId,draftRevision}",
+        "forms.create": "{formId,draftRevision}",
         "workflows.create": "{workflowId,draftRevision}",
         "approvals.create": "{approvalId,draftRevision}",
         "print-templates.create": "{templateId,draftRevision}",
@@ -876,6 +906,10 @@ AUTHORING = {
             "wrong": "select/lookup filter or record value uses the display label",
             "right": "Use opt_/rec_/emp_ ids from objects.get / records.get.",
         },
+        {
+            "wrong": "forms update with the forms.get body, or fields omitted",
+            "right": "Unwrap form, keep every placed field, and set baseRevision from draftRevision. See docs catalogs forms.",
+        },
         {
             "wrong": "records.list.values is the full record",
             "right": "List is a column projection. records.get for all field keys.",
@@ -984,7 +1018,7 @@ APPROVAL_NODE_TYPES = (
 )
 
 FUNCTION_PERMISSIONS = (
-    "workspace.access", "app.manage", "object.manage", "dashboard.manage",
+    "workspace.access", "app.manage", "object.manage", "dashboard.manage", "form.manage",
     "version.manage", "org.manage", "system.manage",
 )
 
@@ -1285,7 +1319,8 @@ RESOURCE_ID_PREFIXES = {
     "reg_": "page region", "cmp_": "page component",
     "dsh_": "dashboard", "dcm_": "dashboard component", "rol_": "role",
     "rec_": "record", "att_": "attachment", "emp_": "employee", "dep_": "department",
-    "ptp_": "print template",
+    "ptp_": "print template", "frm_": "custom form", "fim_": "form image",
+    "rule_": "form or page rule",
 }
 
 WORKFLOW_BRANCHES = {
@@ -1379,6 +1414,110 @@ PRINT_TEMPLATES = {
     "verify": "The management CLI cannot render a template. get returns the source. A saved {{ }} that names the wrong key prints blank. There is no print-templates run command.",
 }
 
+FORMS = {
+    "command": "flowbase docs catalogs forms",
+    "readFirst": (
+        "forms get returns form, fieldOptions, and draftRevision. "
+        "fieldOptions[].availability is the placement contract: placeable, reason, states, "
+        "preset, presetRequired, prefill, plus objectRequired and usableDefault. "
+        "Use field IDs from fieldOptions, never field keys."
+    ),
+    "write": {
+        "create": (
+            "Requires label, key, and objectId. description defaults to empty. "
+            "Placeable object-required fields are pre-added. key starts with a lowercase letter, "
+            "contains only lowercase letters, digits, and underscores, max 50, and cannot change later."
+        ),
+        "update": (
+            "Full snapshot. Requires label, appearance, and settings. "
+            "fields and rules default to [] and clear the form when omitted. "
+            "Copy draftRevision to baseRevision. Unwrap forms.get: do not send the form wrapper, "
+            "id, key, objectId, updatedAt, or fieldOptions."
+        ),
+        "channel": (
+            "set-accepting and reset-link take effect immediately in this environment and are not "
+            "draft changes. copy does not copy collection state or the public link. delete and "
+            "reset-link require --yes."
+        ),
+    },
+    "limits": {
+        "formsPerEnvironment": 200,
+        "fields": 100,
+        "rules": 50,
+        "label": "1 to 50 characters",
+        "description": "max 200 characters",
+        "conditionsPerRule": "1 to 10",
+    },
+    "field": {
+        "requiredKeys": ["fieldId", "label", "description", "state", "prefill"],
+        "optionalKeys": ["preset"],
+        "label": "Display override. Empty string keeps the object field label. Max 100.",
+        "description": "Max 500. Empty string is allowed.",
+        "state": (
+            "One of availability.states. Ordinary fields use required, optional, readonly, hidden. "
+            "lookup.record, lookup.record.multiple, lookup.employee, and lookup.department are "
+            "hidden only. attachment cannot be readonly."
+        ),
+        "prefill": "true only when availability.prefill is true. Hidden-only, attachment, and text.rich cannot be prefilled.",
+        "preset": (
+            "Omit the key when there is no preset. Required when availability.presetRequired. "
+            "A fixed value uses the record value shape from record-values. "
+            "A dynamic preset is {\"mode\":\"dynamic\",\"value\":\"<dynamic default>\"}; currentEmployee is rejected."
+        ),
+        "objectRequired": (
+            "Every placeable object-required field must stay in fields. It cannot be optional. "
+            "readonly or hidden needs a preset unless usableDefault is true."
+        ),
+        "fillable": "At least one placed field is required or optional, or an enabled rule sets one of those states.",
+    },
+    "rule": {
+        "requiredKeys": ["name", "enabled", "match", "conditions", "actions"],
+        "optionalKeys": ["id"],
+        "id": "Omit id, or send a value that does not start with rule_, to allocate a new rule_ id. Preserve an existing rule_ id on update.",
+        "name": "1 to 50 characters, unique in the form.",
+        "match": ["all", "any"],
+        "conditions": (
+            "Same operators as page-rules. Candidates are placed fields that are not "
+            "lookup.record, lookup.record.multiple, lookup.employee, or lookup.department."
+        ),
+        "actions": (
+            "Only setFieldState: {\"type\":\"setFieldState\",\"fieldId\":\"fld_...\",\"state\":\"required\"}. "
+            "state must be in that field's availability.states. No component visibility."
+        ),
+    },
+    "appearance": {
+        "requiredKeys": [
+            "title", "description", "logo", "cover", "themeColor",
+            "background", "submitText", "language",
+        ],
+        "title": "1 to 100 characters.",
+        "description": "Max 2000 characters.",
+        "logo": "null or an existing fim_ id. The management CLI cannot upload images.",
+        "cover": "null or an existing fim_ id. The management CLI cannot upload images.",
+        "themeColor": "#RRGGBB",
+        "background": ["gray", "white", "tint"],
+        "submitText": "Max 20 characters. Empty string is allowed.",
+        "language": ["zh-CN", "en"],
+    },
+    "settings": {
+        "requiredKeys": [
+            "afterSubmit", "successTitle", "successBody", "allowResubmit",
+            "redirectUrl", "deadline", "limit",
+        ],
+        "afterSubmit": ["message", "redirect"],
+        "successTitle": "Max 50 characters.",
+        "successBody": "Max 500 characters.",
+        "redirectUrl": "An https URL when afterSubmit is redirect, max 2048. Otherwise an empty string is allowed.",
+        "deadline": "null, or an ISO-8601 datetime with a timezone. A newly set deadline cannot be in the past.",
+        "limit": "null, or an integer from 1 to 1000000.",
+    },
+    "collectStatus": ["inactive", "invalid", "closed", "deadline", "full", "collecting"],
+    "notInCli": (
+        "Public form read, submit, and attachment upload need no API key and are not management commands. "
+        "Logo and cover upload exist only on the signed-in admin API."
+    ),
+}
+
 CATALOGS = {
     "workflow-branches": WORKFLOW_BRANCHES,
     "approval-rules": APPROVAL_RULES,
@@ -1402,6 +1541,7 @@ CATALOGS = {
     },
     "page-components": PAGE_COMPONENTS,
     "page-rules": PAGE_RULES,
+    "forms": FORMS,
     "id-prefixes": RESOURCE_ID_PREFIXES,
     "icons": {
         "note": "6146 Tabler icon names are supported; any Icon* name from the "

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/src/flowbase_cli/guide.py

@@ -8,7 +8,8 @@ GUIDE = {
         "flowbase apps list；flowbase objects list：发现已有应用和对象，优先复用，不猜测 ID。",
         "flowbase objects get <object_id>：读取字段 key、类型、约束和真实选项 ID；关联字段继续读取目标对象。",
         "flowbase docs catalogs authoring；flowbase docs list；flowbase docs show <endpoint_key>：查请求和更新方式。",
-        "配置页面前读取 pages options、page-components、page-rules、page-buttons；配置流程前读取 workflow-nodes、workflow-branches 或 approval-rules；配置打印模板前读取 print-templates。",
+        "配置页面前读取 pages options、page-components、page-rules、page-buttons；配置流程前读取 workflow-nodes、workflow-branches 或 approval-rules；配置打印模板前读取 print-templates；配置自定义表单前读取 forms。",
+        "表单先 forms get，按目录把快照拆成 label、fields、rules、appearance、settings 再 update，baseRevision 用返回的 draftRevision。对象必填且可放入的字段必须保留。set-accepting 与 reset-link 立即生效，不进草稿。",
         "先 get 再修改，保留未修改的配置。按目录转换更新 envelope；从最近读取或写入返回值获取 draftRevision，作为 baseRevision。",
         "写后回读验证。records create 返回 recordId，再 records get；values 使用字段 key，选择和关联使用真实 ID。",
         "遍历列表的所有分页。records list --view-id <view_id> 验证特定视图，records get 获取完整记录。",
@@ -31,6 +32,7 @@ GUIDE = {
         "docs/guide 离线可读；业务调用需要权限和已启用环境。",
         "页面规则求值不是浏览器渲染；仪表盘输出验证不是图表视觉验证。打印模板 get 返回源码，管理 CLI 不能生成打印内容；写错的 {{ }} 会保存成功并打印成空白。",
         "组织候选只读；不能通过管理 CLI 替员工做审批决定。",
+        "公开表单的读取、提交和附件上传不是管理命令。logo 与 cover 只能引用已有 fim_ 图片，管理 CLI 不能上传图片。",
         "删除对象/字段/页面是逻辑删除；没有物理 purge，审计与回收站会保留。",
     ],
 }

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/src/flowbase_cli/main.py

@@ -522,6 +522,40 @@ def handle_dashboards(args: argparse.Namespace) -> int:
     )
 
 
+def handle_forms(args: argparse.Namespace) -> int:
+    action = args.forms_action
+    if action == "list":
+        return run_request(args, "forms.list")
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {
+                "label": args.label,
+                "key": args.key,
+                "objectId": args.object_id,
+                "description": args.description,
+            },
+            ("label", "key", "objectId"),
+        )
+        return run_request(args, "forms.create", body=body)
+    path_params = {"form_id": args.form_id}
+    if action == "get":
+        return run_request(args, "forms.get", path_params=path_params)
+    if action == "update":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "label", "appearance", "settings")
+        return run_request(args, "forms.update", path_params=path_params, body=body)
+    if action == "copy":
+        return run_request(args, "forms.copy", path_params=path_params)
+    if action == "share":
+        return run_request(args, "forms.share.get", path_params=path_params)
+    if action == "set-accepting":
+        return run_request(args, "forms.share.set-accepting", path_params=path_params, body={"accepting": args.on})
+    if action == "reset-link":
+        return run_request(args, "forms.share.reset", path_params=path_params)
+    return run_request(args, "forms.delete", path_params=path_params)
+
+
 def handle_groups(args: argparse.Namespace) -> int:
     action = args.groups_action
     path = {"app_id": args.app_id}
@@ -1136,6 +1170,37 @@ def build_parser() -> argparse.ArgumentParser:
     add_yes(dashboard_delete)
     dashboards.set_defaults(handler=handle_dashboards)
 
+    forms = groups.add_parser("forms", help="Manage custom forms (public collection links).")
+    form_actions = forms.add_subparsers(dest="forms_action", required=True)
+    form_actions.add_parser("list")
+    form_get = form_actions.add_parser("get")
+    form_get.add_argument("form_id")
+    form_create = form_actions.add_parser("create")
+    form_create.add_argument("--label")
+    form_create.add_argument("--key")
+    form_create.add_argument("--object-id")
+    form_create.add_argument("--description")
+    add_json_args(form_create, endpoint_key="forms.create")
+    form_update = form_actions.add_parser("update")
+    form_update.add_argument("form_id")
+    add_json_args(form_update, endpoint_key="forms.update")
+    form_copy = form_actions.add_parser("copy")
+    form_copy.add_argument("form_id")
+    form_delete = form_actions.add_parser("delete")
+    form_delete.add_argument("form_id")
+    add_yes(form_delete)
+    form_share = form_actions.add_parser("share", help="Show the public link and collection state.")
+    form_share.add_argument("form_id")
+    form_accepting = form_actions.add_parser("set-accepting", help="Turn public collection on or off (immediate).")
+    form_accepting.add_argument("form_id")
+    accepting_group = form_accepting.add_mutually_exclusive_group(required=True)
+    accepting_group.add_argument("--on", dest="on", action="store_true")
+    accepting_group.add_argument("--off", dest="on", action="store_false")
+    form_reset = form_actions.add_parser("reset-link", help="Reset the public link; the old link stops working.")
+    form_reset.add_argument("form_id")
+    add_yes(form_reset)
+    forms.set_defaults(handler=handle_forms)
+
     app_groups = groups.add_parser("groups", help="Manage app object groups.")
     group_actions = app_groups.add_subparsers(dest="groups_action", required=True)
     group_create = group_actions.add_parser("create")

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/src/flowbase_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbase-cli
-Version: 0.1.13
+Version: 0.1.14
 Summary: Command line client for the FlowBase OpenAPI
 Author: DeepFlowAI
 License: Apache-2.0
@@ -125,6 +125,7 @@ flowbase docs catalogs permissions        # function permission points + data sc
 flowbase docs catalogs dashboard-filters  # filter types + date-range presets
 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 forms              # custom form fields, rules, appearance, and settings
 flowbase docs catalogs id-prefixes        # resource ID prefix meanings
 flowbase docs catalogs icons              # icon guidance + examples
 ```

{flowbase_cli-0.1.13 → flowbase_cli-0.1.14}/tests/test_cli.py

@@ -335,6 +335,22 @@ class FlowBaseCliTest(unittest.TestCase):
         self.assertEqual(prefixes["reg_"], "page region")
         self.assertEqual(prefixes["cmp_"], "page component")
         self.assertEqual(prefixes["ptp_"], "print template")
+        self.assertEqual(prefixes["frm_"], "custom form")
+        self.assertEqual(prefixes["fim_"], "form image")
+
+        stdout = io.StringIO()
+        with patch("sys.stdout", stdout):
+            code = main(["docs", "catalogs", "forms"])
+        self.assertEqual(code, 0)
+        forms = json.loads(stdout.getvalue())
+        self.assertEqual(
+            forms["field"]["requiredKeys"],
+            ["fieldId", "label", "description", "state", "prefill"],
+        )
+        self.assertEqual(forms["appearance"]["background"], ["gray", "white", "tint"])
+        self.assertEqual(forms["settings"]["afterSubmit"], ["message", "redirect"])
+        self.assertIn("setFieldState", forms["rule"]["actions"])
+        self.assertIn("forms", names)
 
     def test_docs_list_marks_body_and_confirmation(self):
         stdout = io.StringIO()