@josephyan/qingflow-cli 0.2.0-beta.76 → 0.2.0-beta.78

package/src/qingflow_mcp/tools/record_tools.py

@@ -460,6 +460,8 @@ class RecordTools(ToolBase):
             app_key: str = "",
             record_id: int | None = None,
             fields: JSONObject | None = None,
+            items: list[JSONObject] | None = None,
+            dry_run: bool = False,
             verify_write: bool = True,
             output_profile: str = "normal",
         ) -> JSONObject:
@@ -467,7 +469,9 @@ class RecordTools(ToolBase):
                 profile=DEFAULT_PROFILE,
                 app_key=app_key,
                 record_id=record_id,
-                fields=fields or {},
+                fields=fields,
+                items=items,
+                dry_run=dry_run,
                 verify_write=verify_write,
                 output_profile=output_profile,
             )
@@ -1640,6 +1644,8 @@ class RecordTools(ToolBase):
                     ),
                 }
             )
+        rows = list_data.get("rows", [])
+        normalized_public_rows = _normalize_public_record_rows(rows if isinstance(rows, list) else [])
         response: JSONObject = {
             "profile": profile,
             "ws_id": raw.get("ws_id"),
@@ -1650,7 +1656,7 @@ class RecordTools(ToolBase):
             "output_profile": normalized_output_profile,
             "data": {
                 "app_key": app_key,
-                "items": list_data.get("rows", []),
+                "items": normalized_public_rows,
                 "pagination": {
                     "page": page,
                     "limit": limit,
@@ -1818,7 +1824,7 @@ class RecordTools(ToolBase):
                 "output_profile": normalized_output_profile,
                 "data": {
                     "app_key": app_key,
-                    "record_id": record_id,
+                    "record_id": _public_record_id_text(record_id),
                     "record": row,
                     "selection": {
                         "columns": [_column_selector_payload(field_id) for field_id in normalized_columns] if normalized_columns else [],
@@ -1918,21 +1924,60 @@ class RecordTools(ToolBase):
         app_key: str,
         record_id: int | None,
         fields: JSONObject | None = None,
+        items: list[JSONObject] | None = None,
+        dry_run: bool = False,
         verify_write: bool = True,
         output_profile: str = "normal",
     ) -> JSONObject:
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if items is not None:
+            if dry_run not in {True, False}:
+                raise_tool_error(QingflowApiError.config_error("dry_run must be boolean"))
+            normalized_items = self._normalize_public_record_update_batch_items(
+                record_id=record_id,
+                fields=fields,
+                items=items,
+            )
+            return self._record_update_public_batch(
+                profile=profile,
+                app_key=app_key,
+                items=normalized_items,
+                dry_run=dry_run,
+                verify_write=verify_write,
+                output_profile=normalized_output_profile,
+            )
+        if dry_run:
+            raise_tool_error(QingflowApiError.config_error("dry_run currently requires items"))
         if record_id is None or record_id <= 0:
             raise_tool_error(QingflowApiError.config_error("record_id is required"))
         if fields is not None and not isinstance(fields, dict):
             raise_tool_error(QingflowApiError.config_error("fields must be an object map keyed by field title"))
-        raw_preflight = self._preflight_record_update_with_auto_view(
+        return self._record_update_public_single(
             profile=profile,
             app_key=app_key,
             record_id=record_id,
             fields=cast(JSONObject, fields or {}),
+            verify_write=verify_write,
+            output_profile=normalized_output_profile,
+        )
+
+    def _record_update_public_single(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        fields: JSONObject,
+        verify_write: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        raw_preflight = self._preflight_record_update_with_auto_view(
+            profile=profile,
+            app_key=app_key,
+            record_id=record_id,
+            fields=fields,
             force_refresh_form=False,
         )
         preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
@@ -1950,7 +1995,7 @@ class RecordTools(ToolBase):
                 raw_preflight,
                 operation="update",
                 normalized_payload=normalized_payload,
-                output_profile=normalized_output_profile,
+                output_profile=output_profile,
                 human_review=True,
                 target_resource={"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
             )
@@ -1978,11 +2023,257 @@ class RecordTools(ToolBase):
             raw_apply,
             operation="update",
             normalized_payload=normalized_payload,
-            output_profile=normalized_output_profile,
+            output_profile=output_profile,
             human_review=True,
             preflight=raw_preflight,
         )
 
+    def _record_update_public_batch(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        items: list[JSONObject],
+        dry_run: bool,
+        verify_write: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        preflight_responses = [
+            self._record_update_public_preflight_response(
+                profile=profile,
+                app_key=app_key,
+                record_id=cast(int, item["record_id"]),
+                fields=cast(JSONObject, item["fields"]),
+                output_profile=output_profile,
+            )
+            for item in items
+        ]
+        has_preflight_blockers = any(
+            str(response.get("status") or "").lower() in {"blocked", "needs_confirmation"}
+            for response in preflight_responses
+        )
+        if dry_run or has_preflight_blockers:
+            return self._record_update_batch_response(
+                profile=profile,
+                app_key=app_key,
+                responses=preflight_responses,
+                output_profile=output_profile,
+                dry_run=dry_run,
+            )
+
+        apply_responses: list[JSONObject] = []
+        for item in items:
+            record_id = cast(int, item["record_id"])
+            fields = cast(JSONObject, item["fields"])
+            try:
+                apply_responses.append(
+                    self._record_update_public_single(
+                        profile=profile,
+                        app_key=app_key,
+                        record_id=record_id,
+                        fields=fields,
+                        verify_write=verify_write,
+                        output_profile=output_profile,
+                    )
+                )
+            except (QingflowApiError, RuntimeError) as exc:
+                apply_responses.append(
+                    self._record_write_exception_response(
+                        exc,
+                        operation="update",
+                        profile=profile,
+                        app_key=app_key,
+                        record_id=record_id,
+                        output_profile=output_profile,
+                        human_review=True,
+                    )
+                )
+
+        return self._record_update_batch_response(
+            profile=profile,
+            app_key=app_key,
+            responses=apply_responses,
+            output_profile=output_profile,
+            dry_run=False,
+        )
+
+    def _record_update_public_preflight_response(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        fields: JSONObject,
+        output_profile: str,
+    ) -> JSONObject:
+        raw_preflight = self._preflight_record_update_with_auto_view(
+            profile=profile,
+            app_key=app_key,
+            record_id=record_id,
+            fields=fields,
+            force_refresh_form=False,
+        )
+        preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
+        normalized_payload = self._record_write_normalized_payload(
+            operation="update",
+            record_id=record_id,
+            record_ids=[],
+            normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+            submit_type=1,
+            selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+        )
+        confirmation_requests = cast(list[JSONObject], preflight_data.get("confirmation_requests", []))
+        if preflight_data.get("blockers") or confirmation_requests:
+            return self._record_write_blocked_response(
+                raw_preflight,
+                operation="update",
+                normalized_payload=normalized_payload,
+                output_profile=output_profile,
+                human_review=True,
+                target_resource={"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
+            )
+        return self._record_write_ready_response(
+            raw_preflight,
+            operation="update",
+            normalized_payload=normalized_payload,
+            output_profile=output_profile,
+            human_review=True,
+            target_resource={"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
+        )
+
+    def _normalize_public_record_update_batch_items(
+        self,
+        *,
+        record_id: int | None,
+        fields: JSONObject | None,
+        items: list[JSONObject] | None,
+    ) -> list[JSONObject]:
+        if record_id is not None or fields is not None:
+            raise_tool_error(
+                QingflowApiError.config_error("record_update batch mode does not accept record_id or fields")
+            )
+        if not isinstance(items, list) or not items:
+            raise_tool_error(QingflowApiError.config_error("items must be a non-empty list"))
+        normalized_items: list[JSONObject] = []
+        seen_record_ids: set[int] = set()
+        for index, item in enumerate(items):
+            if not isinstance(item, dict):
+                raise_tool_error(QingflowApiError.config_error(f"items[{index}] must be an object"))
+            normalized_record_id = _coerce_count(item.get("record_id"))
+            if normalized_record_id is None or normalized_record_id <= 0:
+                raise_tool_error(QingflowApiError.config_error(f"items[{index}].record_id must be a positive integer"))
+            if normalized_record_id in seen_record_ids:
+                raise_tool_error(
+                    QingflowApiError.config_error(f"duplicate record_id in items: {normalized_record_id}")
+                )
+            item_fields = item.get("fields")
+            if not isinstance(item_fields, dict):
+                raise_tool_error(QingflowApiError.config_error(f"items[{index}].fields must be an object map keyed by field title"))
+            seen_record_ids.add(normalized_record_id)
+            normalized_items.append({"record_id": normalized_record_id, "fields": cast(JSONObject, item_fields)})
+        return normalized_items
+
+    def _record_update_batch_response(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        responses: list[JSONObject],
+        output_profile: str,
+        dry_run: bool,
+    ) -> JSONObject:
+        summary = self._record_update_batch_summary(responses)
+        batch_items = [self._record_update_batch_item_from_response(response, output_profile=output_profile) for response in responses]
+        status, ok, message = self._record_update_batch_envelope_status(summary=summary, dry_run=dry_run)
+        first_response = responses[0] if responses else {}
+        return {
+            "profile": first_response.get("profile", profile),
+            "ws_id": first_response.get("ws_id"),
+            "ok": ok,
+            "status": status,
+            "request_route": first_response.get("request_route"),
+            "warnings": [],
+            "output_profile": output_profile,
+            "data": {
+                "app_key": app_key,
+                "mode": "batch",
+                "dry_run": dry_run,
+                "summary": summary,
+                "items": batch_items,
+            },
+            "message": message,
+        }
+
+    def _record_update_batch_summary(self, responses: list[JSONObject]) -> JSONObject:
+        summary: JSONObject = {
+            "total": len(responses),
+            "ready_count": 0,
+            "blocked_count": 0,
+            "confirmation_count": 0,
+            "applied_count": 0,
+            "verified_count": 0,
+            "field_level_verified_count": 0,
+            "failed_count": 0,
+        }
+        for response in responses:
+            status = str(response.get("status") or "").lower()
+            data = cast(JSONObject, response.get("data", {}))
+            action = cast(JSONObject, data.get("action", {}))
+            verification = cast(JSONObject, data.get("verification", {})) if isinstance(data.get("verification"), dict) else {}
+            executed = bool(action.get("executed"))
+            if status == "ready":
+                summary["ready_count"] = int(summary["ready_count"]) + 1
+                continue
+            if status == "blocked":
+                summary["blocked_count"] = int(summary["blocked_count"]) + 1
+                continue
+            if status == "needs_confirmation":
+                summary["confirmation_count"] = int(summary["confirmation_count"]) + 1
+                continue
+            if executed:
+                summary["applied_count"] = int(summary["applied_count"]) + 1
+            if bool(verification.get("verified")):
+                summary["verified_count"] = int(summary["verified_count"]) + 1
+            if bool(verification.get("field_level_verified")):
+                summary["field_level_verified_count"] = int(summary["field_level_verified_count"]) + 1
+            if status not in {"success"}:
+                summary["failed_count"] = int(summary["failed_count"]) + 1
+        return summary
+
+    def _record_update_batch_envelope_status(self, *, summary: JSONObject, dry_run: bool) -> tuple[str, bool, str]:
+        if int(summary["blocked_count"]) > 0:
+            return "blocked", False, "batch update preflight blocked"
+        if int(summary["confirmation_count"]) > 0:
+            return "needs_confirmation", False, "batch update requires confirmation before write"
+        if dry_run:
+            return "ready", True, "batch update dry run ready"
+        if int(summary["failed_count"]) > 0:
+            return "partial_success", False, "batch update completed with partial failures"
+        return "success", True, "batch update completed"
+
+    def _record_update_batch_item_from_response(self, response: JSONObject, *, output_profile: str) -> JSONObject:
+        data = cast(JSONObject, response.get("data", {}))
+        item: JSONObject = {
+            "resource": data.get("resource"),
+            "status": response.get("status"),
+            "verification": data.get("verification"),
+            "field_errors": cast(list[JSONObject], data.get("field_errors", [])),
+            "confirmation_requests": cast(list[JSONObject], data.get("confirmation_requests", [])),
+            "resolved_fields": cast(list[JSONObject], data.get("resolved_fields", [])),
+        }
+        blockers = data.get("blockers")
+        if isinstance(blockers, list) and blockers:
+            item["blockers"] = blockers
+        warnings = response.get("warnings")
+        if isinstance(warnings, list) and warnings:
+            item["warnings"] = warnings
+        error = data.get("error")
+        if isinstance(error, dict):
+            item["error"] = error
+        if output_profile == "verbose" and isinstance(data.get("debug"), dict):
+            item["debug"] = data.get("debug")
+        return item
+
     def _preflight_record_update_with_auto_view(
         self,
         *,
@@ -7944,6 +8235,48 @@ class RecordTools(ToolBase):
             }
         return response
 
+    def _record_write_ready_response(
+        self,
+        raw_preflight: JSONObject,
+        *,
+        operation: str,
+        normalized_payload: JSONObject,
+        output_profile: str,
+        human_review: bool,
+        target_resource: JSONObject,
+    ) -> JSONObject:
+        plan_data = cast(JSONObject, raw_preflight.get("data", {}))
+        validation = cast(JSONObject, plan_data.get("validation", {}))
+        resolved_fields = cast(list[JSONObject], plan_data.get("lookup_resolved_fields", []))
+        warnings_payload = validation.get("warnings", [])
+        warnings = [{"code": "PREFLIGHT_WARNING", "message": str(item)} for item in warnings_payload] if isinstance(warnings_payload, list) else []
+        response: JSONObject = {
+            "profile": raw_preflight.get("profile"),
+            "ws_id": raw_preflight.get("ws_id"),
+            "ok": True,
+            "status": "ready",
+            "request_route": raw_preflight.get("request_route"),
+            "warnings": warnings,
+            "output_profile": output_profile,
+            "data": {
+                "action": {"operation": operation, "executed": False},
+                "resource": target_resource,
+                "verification": None,
+                "normalized_payload": normalized_payload,
+                "blockers": [],
+                "field_errors": [],
+                "confirmation_requests": [],
+                "resolved_fields": resolved_fields,
+                "recommended_next_actions": cast(list[JSONValue], plan_data.get("recommended_next_actions", [])),
+                "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
+            },
+        }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {
+                "preflight": plan_data,
+            }
+        return response
+
     def _record_write_apply_response(
         self,
         raw_apply: JSONObject,
@@ -7994,6 +8327,67 @@ class RecordTools(ToolBase):
             response["data"]["debug"] = debug
         return response
 
+    def _record_write_exception_response(
+        self,
+        exc: QingflowApiError | RuntimeError,
+        *,
+        operation: str,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        output_profile: str,
+        human_review: bool,
+    ) -> JSONObject:
+        error_payload: JSONObject = {
+            "error_code": "RECORD_WRITE_EXECUTION_FAILED",
+            "message": str(exc),
+        }
+        request_route: JSONObject | None = None
+        if isinstance(exc, QingflowApiError):
+            error_payload["message"] = exc.message
+            if exc.backend_code is not None:
+                error_payload["backend_code"] = exc.backend_code
+            if exc.request_id is not None:
+                error_payload["request_id"] = exc.request_id
+        else:
+            try:
+                parsed = json.loads(str(exc))
+            except json.JSONDecodeError:
+                parsed = None
+            if isinstance(parsed, dict):
+                error_payload["error_code"] = parsed.get("error_code") or cast(JSONObject, parsed.get("details", {})).get("error_code") or error_payload["error_code"]
+                error_payload["message"] = parsed.get("message") or error_payload["message"]
+                if parsed.get("backend_code") is not None:
+                    error_payload["backend_code"] = parsed.get("backend_code")
+                if parsed.get("request_id") is not None:
+                    error_payload["request_id"] = parsed.get("request_id")
+                if isinstance(parsed.get("request_route"), dict):
+                    request_route = cast(JSONObject, parsed.get("request_route"))
+        response: JSONObject = {
+            "profile": profile,
+            "ws_id": None,
+            "ok": False,
+            "status": "failed",
+            "request_route": request_route,
+            "warnings": [],
+            "output_profile": output_profile,
+            "data": {
+                "action": {"operation": operation, "executed": True},
+                "resource": {"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
+                "verification": None,
+                "normalized_payload": None,
+                "blockers": [],
+                "field_errors": [],
+                "confirmation_requests": [],
+                "resolved_fields": [],
+                "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
+                "error": error_payload,
+            },
+        }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {"exception": error_payload}
+        return response
+
     def _record_write_public_field_errors(self, plan_data: JSONObject) -> list[JSONObject]:
         existing = plan_data.get("field_errors")
         if isinstance(existing, list):
@@ -10221,12 +10615,36 @@ def _view_selection_supported_by_search_ids(view_selection: ViewSelection, searc
 
 
 def _build_flat_row(answer_list: list[JSONValue], fields: list[FormField], *, apply_id: int | None) -> JSONObject:
-    row: JSONObject = {"apply_id": apply_id}
+    public_record_id = _public_record_id_text(apply_id)
+    row: JSONObject = {"apply_id": public_record_id, "record_id": public_record_id}
     for field in fields:
         row[field.que_title] = _extract_field_value(answer_list, field)
     return row
 
 
+def _public_record_id_text(record_id: int | None) -> str | None:
+    if record_id is None or record_id <= 0:
+        return None
+    return str(record_id)
+
+
+def _normalize_public_record_rows(rows: list[JSONValue]) -> list[JSONObject]:
+    normalized_rows: list[JSONObject] = []
+    for item in rows:
+        if not isinstance(item, dict):
+            continue
+        row = dict(item)
+        normalized_record_id = _coerce_count(row.get("apply_id"))
+        if normalized_record_id is None:
+            normalized_record_id = _coerce_count(row.get("record_id"))
+        if normalized_record_id is not None and normalized_record_id > 0:
+            public_record_id = _public_record_id_text(normalized_record_id)
+            row["apply_id"] = public_record_id
+            row["record_id"] = public_record_id
+        normalized_rows.append(row)
+    return normalized_rows
+
+
 def _merge_answer_lists_by_field_id(existing: list[JSONValue], extra: list[JSONValue]) -> list[JSONValue]:
     merged: dict[str, JSONValue] = {}
     order: list[str] = []