ktr-cli 0.1.0__py3-none-any.whl

kantree_cli/core/response.py

@@ -0,0 +1,86 @@
+from typing import Any, Callable
+
+from kantree_cli.core.errors import ValidationError
+
+JsonObject = dict[str, Any]
+
+
+def extract_object_list(
+    payload: Any,
+    *,
+    context: str,
+    preferred_keys: tuple[str, ...],
+) -> list[JsonObject]:
+    if isinstance(payload, list):
+        return normalize_object_list(payload, context=context)
+
+    if isinstance(payload, dict):
+        for key in preferred_keys:
+            maybe_list = payload.get(key)
+            if isinstance(maybe_list, list):
+                return normalize_object_list(maybe_list, context=context)
+
+    raise ValidationError(f"Unexpected response payload for {context}: expected a list.")
+
+
+def extract_object(
+    payload: Any,
+    *,
+    context: str,
+    preferred_keys: tuple[str, ...],
+    require_id_field: bool = True,
+    object_check: Callable[[JsonObject], bool] | None = None,
+) -> JsonObject:
+    if isinstance(payload, dict):
+        if require_id_field and "id" in payload:
+            return payload
+        if object_check is not None and object_check(payload):
+            return payload
+        for key in preferred_keys:
+            maybe_object = payload.get(key)
+            if isinstance(maybe_object, dict):
+                return maybe_object
+
+    raise ValidationError(f"Unexpected response payload for {context}: expected an object.")
+
+
+def normalize_object_list(items: list[Any], *, context: str) -> list[JsonObject]:
+    normalized: list[JsonObject] = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ValidationError(f"Unexpected item type at index {index} for {context}.")
+        normalized.append(item)
+    return normalized
+
+
+def next_page_header_value(headers: dict[str, str]) -> int | None:
+    raw_next_page = headers.get("X-Kantree-NextPage")
+    if raw_next_page is None:
+        raw_next_page = headers.get("x-kantree-nextpage")
+    if raw_next_page is None:
+        return None
+
+    normalized = raw_next_page.strip()
+    if not normalized:
+        return None
+
+    parsed = _parse_int(normalized)
+    if parsed is None or parsed < 1:
+        return None
+    return parsed
+
+
+def _parse_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        try:
+            return int(stripped)
+        except ValueError:
+            return None
+    return None

kantree_cli/services/__init__.py

@@ -0,0 +1 @@
+"""Service helpers for command-level workflows."""