applied-cli 0.1.0__py3-none-any.whl

applied_cli/http.py

@@ -0,0 +1,1614 @@
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+
+class APIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        *,
+        code: str | None = None,
+        hint: str | None = None,
+        retryable: bool | None = None,
+        method: str | None = None,
+        url: str | None = None,
+        detail: Any = None,
+        suggestions: list[str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.hint = hint
+        self.retryable = retryable
+        self.method = method
+        self.url = url
+        self.detail = detail
+        self.suggestions = suggestions or []
+
+
+def _auth_headers(*, shop_id: str, api_token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_token}",
+        "X-Shop-Id": shop_id,
+        "Content-Type": "application/json",
+    }
+
+
+def _token_headers(*, api_token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_token}",
+        "Content-Type": "application/json",
+    }
+
+
+def _error_detail(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except Exception:
+        return response.text
+
+
+def _build_api_error(
+    *,
+    method: str,
+    url: str,
+    status_code: int,
+    detail: Any,
+) -> APIError:
+    code = "API_REQUEST_FAILED"
+    hint = "Retry after checking inputs and credentials."
+    retryable = status_code >= 500
+    suggestions: list[str] = []
+
+    if status_code == 401:
+        code = "AUTH_INVALID_TOKEN"
+        hint = "Token rejected by server. Run `applied-cli auth login` again."
+        retryable = False
+        suggestions.extend(
+            [
+                "Verify APPLIED_API_TOKEN or stored token value.",
+                "Run `applied-cli auth status` to validate token and shop scope.",
+            ]
+        )
+    elif status_code == 403:
+        code = "SHOP_SCOPE_FORBIDDEN"
+        hint = "Credentials lack permission for this shop or resource."
+        retryable = False
+        suggestions.extend(
+            [
+                "Confirm `--shop-id` matches the shop your token can access.",
+                "If using admin JWT/API token, ensure X-Shop-Id is set correctly.",
+            ]
+        )
+    elif status_code == 404:
+        code = "RESOURCE_NOT_FOUND"
+        hint = "Requested resource was not found in the selected shop scope."
+        retryable = False
+        if "/agents/" in url:
+            suggestions.append(
+                "Verify `--agent-id` belongs to the target shop and exists."
+            )
+        elif "/conversations/" in url:
+            suggestions.append(
+                "Verify `--conversation-id` belongs to the target shop and exists."
+            )
+    elif status_code == 400:
+        code = "INVALID_REQUEST"
+        hint = "Request payload is invalid for this endpoint."
+        retryable = False
+        suggestions.append("Check required fields and allowed enum values.")
+
+    detail_text = str(detail).lower()
+    if "/v1/conversation-benchmarks/" in url and "agent_id" in detail_text:
+        code = "BENCHMARK_MISSING_AGENT"
+        hint = "Benchmark creation requires an agent id in payload."
+        retryable = False
+        suggestions.append(
+            "Pass the target agent UUID when creating benchmark records."
+        )
+
+    return APIError(
+        f"Applied API request failed ({status_code}) {method} {url}",
+        status_code=status_code,
+        code=code,
+        hint=hint,
+        retryable=retryable,
+        method=method,
+        url=url,
+        detail=detail,
+        suggestions=suggestions,
+    )
+
+
+def _request_json(
+    *,
+    method: str,
+    url: str,
+    shop_id: str,
+    api_token: str,
+    timeout_seconds: float = 20.0,
+    payload: dict[str, Any] | None = None,
+) -> Any:
+    try:
+        response = httpx.request(
+            method=method,
+            url=url,
+            headers=_auth_headers(shop_id=shop_id, api_token=api_token),
+            timeout=timeout_seconds,
+            json=payload,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method=method,
+            url=url,
+        ) from exc
+
+    if response.status_code >= 400:
+        detail = _error_detail(response)
+        raise _build_api_error(
+            method=method,
+            url=url,
+            status_code=response.status_code,
+            detail=detail,
+        )
+    try:
+        return response.json()
+    except Exception as exc:
+        raise APIError(
+            f"Applied API returned non-JSON response for {method} {url}.",
+            code="NON_JSON_RESPONSE",
+            hint="Server returned an unexpected response format.",
+            retryable=False,
+            method=method,
+            url=url,
+        ) from exc
+
+
+def _request_no_content(
+    *,
+    method: str,
+    url: str,
+    shop_id: str,
+    api_token: str,
+    timeout_seconds: float = 20.0,
+) -> None:
+    try:
+        response = httpx.request(
+            method=method,
+            url=url,
+            headers=_auth_headers(shop_id=shop_id, api_token=api_token),
+            timeout=timeout_seconds,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method=method,
+            url=url,
+        ) from exc
+
+    if response.status_code >= 400:
+        detail = _error_detail(response)
+        raise _build_api_error(
+            method=method,
+            url=url,
+            status_code=response.status_code,
+            detail=detail,
+        )
+
+
+def _results_list(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [item for item in data if isinstance(item, dict)]
+    if isinstance(data, dict):
+        results = data.get("results")
+        if isinstance(results, list):
+            return [item for item in results if isinstance(item, dict)]
+    return []
+
+
+def validate_api_token(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    timeout_seconds: float = 10.0,
+) -> dict[str, Any]:
+    url = f"{base_url}/v1/tokens/?type=api_token"
+    try:
+        response = httpx.get(
+            url,
+            headers=_auth_headers(shop_id=shop_id, api_token=api_token),
+            timeout=timeout_seconds,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method="GET",
+            url=url,
+        ) from exc
+
+    if response.status_code >= 400:
+        detail = _error_detail(response)
+        raise APIError(
+            f"Token validation failed ({response.status_code}).",
+            status_code=response.status_code,
+            code="AUTH_TOKEN_VALIDATION_FAILED",
+            hint="Token or shop scope is invalid for this request.",
+            retryable=False,
+            method="GET",
+            url=url,
+            detail=detail,
+            suggestions=[
+                "Run `applied-cli auth login` and paste a fresh API token.",
+                "Verify APPLIED_SHOP_ID / --shop-id is the intended shop.",
+            ],
+        )
+
+    try:
+        return response.json()
+    except Exception as exc:
+        raise APIError(
+            "Applied API returned non-JSON validation response.",
+            code="NON_JSON_RESPONSE",
+            hint="Server returned an unexpected response format.",
+            retryable=False,
+            method="GET",
+            url=url,
+        ) from exc
+
+
+def list_accessible_shops(
+    *,
+    base_url: str,
+    api_token: str,
+    timeout_seconds: float = 10.0,
+) -> list[dict[str, Any]]:
+    candidate_urls = [
+        f"{base_url}/v1/shops/accessible/",
+        f"{base_url}/v1/shops/",
+    ]
+    last_error: APIError | None = None
+    for url in candidate_urls:
+        try:
+            response = httpx.get(
+                url,
+                headers=_token_headers(api_token=api_token),
+                timeout=timeout_seconds,
+            )
+        except httpx.HTTPError as exc:
+            last_error = APIError(
+                f"Failed to reach Applied API: {exc}",
+                code="NETWORK_ERROR",
+                hint=(
+                    "Check APPLIED_BASE_URL and confirm the server is reachable "
+                    "(for local dev: `http://localhost:8000`)."
+                ),
+                retryable=True,
+                method="GET",
+                url=url,
+            )
+            continue
+
+        if response.status_code >= 400:
+            detail = _error_detail(response)
+            last_error = _build_api_error(
+                method="GET",
+                url=url,
+                status_code=response.status_code,
+                detail=detail,
+            )
+            continue
+
+        try:
+            payload = response.json()
+        except Exception as exc:
+            raise APIError(
+                "Shops listing returned non-JSON response.",
+                code="NON_JSON_RESPONSE",
+                hint="Server returned an unexpected response format.",
+                retryable=False,
+                method="GET",
+                url=url,
+            ) from exc
+        shops = _results_list(payload)
+        if shops:
+            return shops
+
+    if last_error is not None:
+        raise last_error
+    return []
+
+
+def start_cli_device_login(
+    *,
+    base_url: str,
+    timeout_seconds: float = 10.0,
+) -> dict[str, Any]:
+    url = f"{base_url}/v1/cli/device/start/"
+    try:
+        response = httpx.post(url, timeout=timeout_seconds, json={})
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method="POST",
+            url=url,
+        ) from exc
+    if response.status_code >= 400:
+        raise _build_api_error(
+            method="POST",
+            url=url,
+            status_code=response.status_code,
+            detail=_error_detail(response),
+        )
+    try:
+        payload = response.json()
+    except Exception as exc:
+        raise APIError(
+            "Device login start returned non-JSON response.",
+            code="NON_JSON_RESPONSE",
+            hint="Server returned an unexpected response format.",
+            retryable=False,
+            method="POST",
+            url=url,
+        ) from exc
+    if not isinstance(payload, dict):
+        raise APIError("Device login start response is not an object.")
+    return payload
+
+
+def poll_cli_device_login(
+    *,
+    base_url: str,
+    device_code: str,
+    timeout_seconds: float = 10.0,
+) -> dict[str, Any]:
+    url = f"{base_url}/v1/cli/device/token/"
+    try:
+        response = httpx.post(
+            url,
+            json={"device_code": device_code},
+            timeout=timeout_seconds,
+            headers={"Content-Type": "application/json"},
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method="POST",
+            url=url,
+        ) from exc
+    if response.status_code >= 400:
+        raise _build_api_error(
+            method="POST",
+            url=url,
+            status_code=response.status_code,
+            detail=_error_detail(response),
+        )
+    try:
+        payload = response.json()
+    except Exception as exc:
+        raise APIError(
+            "Device login poll returned non-JSON response.",
+            code="NON_JSON_RESPONSE",
+            hint="Server returned an unexpected response format.",
+            retryable=False,
+            method="POST",
+            url=url,
+        ) from exc
+    if not isinstance(payload, dict):
+        raise APIError("Device login poll response is not an object.")
+    return payload
+
+
+def get_conversation(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/{conversation_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Conversation response is not an object.")
+    return data
+
+
+def delete_conversation(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> None:
+    _request_no_content(
+        method="DELETE",
+        url=f"{base_url}/v1/conversations/{conversation_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def import_conversations_bulk(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    file_path: Optional[str] = None,
+    url: Optional[str] = None,
+    process_labels: bool = False,
+    timeout_seconds: float = 120.0,
+) -> dict[str, Any]:
+    if bool(file_path) == bool(url):
+        raise APIError(
+            "Provide exactly one source: file_path or url.",
+            code="INVALID_IMPORT_SOURCE",
+            hint="Use --file-path for local CSV or --url for remote CSV.",
+            retryable=False,
+        )
+
+    request_url = f"{base_url}/v1/conversations/bulk-upload/"
+    headers = {
+        "Authorization": f"Bearer {api_token}",
+        "X-Shop-Id": shop_id,
+    }
+    data = {
+        "agent_id": agent_id,
+        "process_labels": "true" if process_labels else "false",
+    }
+    files = None
+    stream = None
+    if file_path:
+        stream = open(file_path, "rb")
+        files = {"file": (file_path.split("/")[-1], stream, "text/csv")}
+    else:
+        data["url"] = str(url)
+
+    try:
+        response = httpx.post(
+            request_url,
+            headers=headers,
+            data=data,
+            files=files,
+            timeout=timeout_seconds,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Failed to reach Applied API: {exc}",
+            code="NETWORK_ERROR",
+            hint=(
+                "Check APPLIED_BASE_URL and confirm the server is reachable "
+                "(for local dev: `http://localhost:8000`)."
+            ),
+            retryable=True,
+            method="POST",
+            url=request_url,
+            suggestions=[
+                "Verify file path or URL is accessible from your environment.",
+            ],
+        ) from exc
+    finally:
+        if stream is not None:
+            stream.close()
+
+    if response.status_code >= 400:
+        detail = _error_detail(response)
+        exc = _build_api_error(
+            method="POST",
+            url=request_url,
+            status_code=response.status_code,
+            detail=detail,
+        )
+        detail_text = str(detail).lower()
+        if "phone" in detail_text:
+            exc.suggestions.extend(
+                [
+                    "CONTACT_PHONE can be omitted; importer now fills safe placeholders.",
+                    "If your CSV has malformed phones, keep them short (<=16 chars) or E.164-like (for example +15551234567).",
+                ]
+            )
+        exc.suggestions.extend(
+            [
+                "Expected CSV headers: ID, DATE_CREATED, SENDER, TYPE, MESSAGE_DATE, BODY, TITLE, TOPIC, INTENT, SENTIMENT, SENTIMENT_SCORE, CSAT_SCORE.",
+                "Optional headers: CONTACT_NAME, CONTACT_EMAIL, CONTACT_PHONE, RESOLUTION_STATUS.",
+            ]
+        )
+        raise exc
+
+    try:
+        payload = response.json()
+    except Exception as exc:
+        raise APIError(
+            "Bulk import returned non-JSON response.",
+            code="NON_JSON_RESPONSE",
+            hint="Server returned an unexpected response format.",
+            retryable=False,
+            method="POST",
+            url=request_url,
+        ) from exc
+    if not isinstance(payload, dict):
+        raise APIError("Bulk import response is not an object.")
+    return payload
+
+
+def list_conversations(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str | None = None,
+    conversation_type: str | None = None,
+    response_type: str | None = None,
+    is_test: bool | None = None,
+    limit: int = 20,
+    offset: int = 0,
+    ordering: str = "-created_at",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params: dict[str, str] = {
+        "limit": str(limit),
+        "offset": str(offset),
+        "ordering": ordering,
+    }
+    if agent_id:
+        params["agent_id"] = agent_id
+    if conversation_type:
+        params["type"] = conversation_type
+    if response_type:
+        params["response_type"] = response_type
+    if is_test is not None:
+        params["is_test"] = "true" if is_test else "false"
+    query = urlencode(params)
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/?{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def list_property_choices(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    ordering: str = "name",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    query = urlencode({"ordering": ordering})
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/property-choices/?{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def list_conversation_messages(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/messages/?conversation_id={conversation_id}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def list_conversation_references(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/{conversation_id}/references/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def list_conversation_benchmarks(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str | None = None,
+    limit: int = 50,
+    ordering: str = "-created_at",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params: dict[str, str] = {
+        "limit": str(limit),
+        "ordering": ordering,
+    }
+    if agent_id:
+        params["agent"] = agent_id
+    query = urlencode(params)
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversation-benchmarks/?{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def get_conversation_benchmark(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    benchmark_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversation-benchmarks/{benchmark_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Benchmark response is not an object.")
+    return data
+
+
+def create_conversation_benchmark(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    name: str,
+    description: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/conversation-benchmarks/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload={
+            "agent": agent_id,
+            "name": name,
+            "description": description,
+        },
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create benchmark response is not an object.")
+    return data
+
+
+def delete_conversation_benchmark(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    benchmark_id: str,
+    timeout_seconds: float = 20.0,
+) -> None:
+    _request_no_content(
+        method="DELETE",
+        url=f"{base_url}/v1/conversation-benchmarks/{benchmark_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def list_conversation_scenarios(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str | None = None,
+    name: str | None = None,
+    benchmark_id: str | None = None,
+    pass_status: str | None = None,
+    limit: int = 50,
+    ordering: str = "-created_at",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params: dict[str, str] = {
+        "limit": str(limit),
+        "ordering": ordering,
+    }
+    if agent_id:
+        params["agent"] = agent_id
+    if name:
+        params["name"] = name
+    if benchmark_id:
+        params["benchmark"] = benchmark_id
+    if pass_status:
+        params["pass_status"] = pass_status
+    query = urlencode(params)
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversation-scenarios/?{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def create_conversation_scenario(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    benchmark_id: str | None,
+    name: str,
+    input_conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "agent_id": agent_id,
+        "name": name,
+        "input_conversation_id": input_conversation_id,
+    }
+    if benchmark_id:
+        payload["benchmark_ids"] = [benchmark_id]
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/conversation-scenarios/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create scenario response is not an object.")
+    return data
+
+
+def patch_conversation_scenario(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    scenario_id: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="PATCH",
+        url=f"{base_url}/v1/conversation-scenarios/{scenario_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Patch scenario response is not an object.")
+    return data
+
+
+def delete_conversation_scenario(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    scenario_id: str,
+    timeout_seconds: float = 20.0,
+) -> None:
+    _request_no_content(
+        method="DELETE",
+        url=f"{base_url}/v1/conversation-scenarios/{scenario_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def get_conversation_scenario(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    scenario_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversation-scenarios/{scenario_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Get scenario response is not an object.")
+    return data
+
+
+def list_scenario_runs(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    scenario_id: str,
+    latest_only: bool = True,
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    latest_value = "true" if latest_only else "false"
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/scenario-runs/?scenario={scenario_id}&latest={latest_value}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def create_scenario_run(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    scenario_id: str,
+    output_conversation_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/scenario-runs/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload={
+            "scenario": scenario_id,
+            "output_conversation_id": output_conversation_id,
+        },
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create scenario run response is not an object.")
+    return data
+
+
+def patch_scenario_run(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    run_id: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="PATCH",
+        url=f"{base_url}/v1/scenario-runs/{run_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Patch scenario run response is not an object.")
+    return data
+
+
+def get_scenario_run(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    run_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/scenario-runs/{run_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Get scenario run response is not an object.")
+    return data
+
+
+def create_agent(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/agents/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create agent response is not an object.")
+    return data
+
+
+def get_agent(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/agents/{agent_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Get agent response is not an object.")
+    return data
+
+
+def list_agents(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    limit: int = 100,
+    ordering: str = "-created_at",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params = urlencode({"limit": str(limit), "ordering": ordering})
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/agents/?{params}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def update_agent(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="PATCH",
+        url=f"{base_url}/v1/agents/{agent_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Update agent response is not an object.")
+    return data
+
+
+def list_responses(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str | None = None,
+    response_type: str | None = None,
+    active: bool | None = None,
+    limit: int = 100,
+    ordering: str = "-updated_at",
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params: dict[str, str] = {
+        "limit": str(limit),
+        "ordering": ordering,
+    }
+    if agent_id:
+        params["agent_id"] = agent_id
+    if response_type:
+        params["type"] = response_type
+    if active is not None:
+        params["active"] = "true" if active else "false"
+    query = urlencode(params)
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/responses/?{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return _results_list(data)
+
+
+def get_response(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    response_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/responses/{response_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Get response response is not an object.")
+    return data
+
+
+def create_response(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/responses/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create response response is not an object.")
+    return data
+
+
+def patch_response(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    response_id: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="PATCH",
+        url=f"{base_url}/v1/responses/{response_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Patch response response is not an object.")
+    return data
+
+
+def simulate_agent_conversation(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    payload: dict[str, Any],
+    timeout_seconds: float = 60.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v2/agents/{agent_id}/simulate/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Simulate response is not an object.")
+    return data
+
+
+def insights_generate(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    instruction: str | None = None,
+    date_range: str | None = None,
+    filters: dict[str, Any] | None = None,
+    conversation_ids: list[str] | None = None,
+    data_source: str | None = None,
+    timeout_seconds: float = 30.0,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    if instruction is not None:
+        payload["instruction"] = instruction
+    if date_range is not None:
+        payload["date_range"] = date_range
+    if filters is not None:
+        payload["filters"] = filters
+    if conversation_ids is not None:
+        payload["conversation_ids"] = conversation_ids
+    if data_source is not None:
+        payload["data_source"] = data_source
+
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/conversations/insights-generate/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Insights generate response is not an object.")
+    return data
+
+
+def insights_followup(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    instruction: str,
+    parent_report_id: str,
+    date_range: str | None = None,
+    conversation_ids: list[str] | None = None,
+    timeout_seconds: float = 30.0,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "instruction": instruction,
+        "parent_report_id": parent_report_id,
+    }
+    if date_range is not None:
+        payload["date_range"] = date_range
+    if conversation_ids is not None:
+        payload["conversation_ids"] = conversation_ids
+
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/conversations/insights-followup/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Insights followup response is not an object.")
+    return data
+
+
+def get_insights_status(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    report_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/insights-status/{report_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Insights status response is not an object.")
+    return data
+
+
+def list_insights_reports(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    status: str | None = None,
+    configuration_id: str | None = None,
+    parent_report_id: str | None = None,
+    timeout_seconds: float = 20.0,
+) -> list[dict[str, Any]]:
+    params: dict[str, str] = {}
+    if status:
+        params["status"] = status
+    if configuration_id:
+        params["configuration_id"] = configuration_id
+    if parent_report_id:
+        params["parent_report_id"] = parent_report_id
+
+    query = f"?{urlencode(params)}" if params else ""
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/insights-reports/{query}",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Insights reports response is not an object.")
+    return _results_list(data.get("reports"))
+
+
+def get_insights_report(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    report_id: str,
+    timeout_seconds: float = 20.0,
+) -> dict[str, Any]:
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/conversations/insights-reports/{report_id}/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Insights report response is not an object.")
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Shop management
+# ---------------------------------------------------------------------------
+
+
+def create_shop(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    name: str,
+    timeout_seconds: float = 30.0,
+) -> dict[str, Any]:
+    """Create a new shop.
+
+    ``shop_id`` is the *admin* shop's UUID used in the ``X-Shop-Id`` header for
+    authentication.  The backend restricts this endpoint to Applied's main/demo
+    team IDs and auto-mints a ``setup_token`` for the new shop which is returned
+    in the response (only returned at creation time).
+    """
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/shops/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload={"name": name},
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create shop response is not an object.")
+    return data
+
+
+def create_content_source(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    url: str,
+    title: Optional[str] = None,
+    timeout_seconds: float = 30.0,
+) -> dict[str, Any]:
+    """Create a website-type knowledge-base content source for a shop."""
+    payload: dict[str, Any] = {
+        "type": "website",
+        "source": url,
+    }
+    if title:
+        payload["title"] = title
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/content-source/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create content source response is not an object.")
+    return data
+
+
+def create_property_choice(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    name: str,
+    description: str = "",
+    parent_choice_id: Optional[str] = None,
+    timeout_seconds: float = 15.0,
+) -> dict[str, Any]:
+    """Create a topic (no parent) or intent (with parent) in the shop taxonomy.
+
+    Topics and intents are both ``PropertyChoice`` objects.  A topic has no
+    ``parent_choice``; an intent has ``parent_choice`` set to its topic's ID.
+    """
+    payload: dict[str, Any] = {
+        "name": name,
+        "color": "blue",
+        "field_id": None,
+    }
+    if description:
+        payload["description"] = description
+    if parent_choice_id:
+        payload["parent_choice_id"] = parent_choice_id
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/property-choices/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Create property choice response is not an object.")
+    return data
+
+
+def check_superuser(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    timeout_seconds: float = 10.0,
+) -> bool:
+    """Return True if the current API token belongs to a superuser."""
+    data = _request_json(
+        method="GET",
+        url=f"{base_url}/v1/users/check-superuser/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+    )
+    return bool(data.get("is_superuser"))
+
+
+def populate_demo_shop(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    target_shop_id: str,
+    distribution: list[dict[str, Any]],
+    date_from: str,
+    date_to: str,
+    num_conversations: int = 20,
+    delete_previous: bool = False,
+    max_turns: int = 3,
+    timeout_seconds: float = 60.0,
+) -> dict[str, Any]:
+    """Enqueue demo simulated conversations for a shop.
+
+    Requires a superuser API token or JWT passed as ``api_token``.
+    ``shop_id`` is the *admin* shop ID used in the ``X-Shop-Id`` header.
+    ``target_shop_id`` is the shop to populate and is sent in the request body.
+    """
+    payload: dict[str, Any] = {
+        "shop_id": target_shop_id,
+        "distribution": distribution,
+        "date_from": date_from,
+        "date_to": date_to,
+        "num_conversations": num_conversations,
+        "delete_previous": delete_previous,
+        "max_turns": max_turns,
+    }
+    data = _request_json(
+        method="POST",
+        url=f"{base_url}/v1/users/populate-demo-shop/",
+        shop_id=shop_id,
+        api_token=api_token,
+        timeout_seconds=timeout_seconds,
+        payload=payload,
+    )
+    if not isinstance(data, dict):
+        raise APIError("Populate demo shop response is not an object.")
+    return data
+
+
+_ESCALATION_FLOW_TEMPLATE: dict[str, Any] = {
+    "name": "escalate_conversation",
+    "description": "",
+    "prompt": "",
+    "trigger": "llm.call",
+    "sync_enabled": False,
+    "resync_schedule": "",
+    "type": "operational",
+    "status": "Active",
+    "nodes": [
+        {
+            "id": "node-trigger",
+            "name": "trigger",
+            "description": "",
+            "prompt": "",
+            "metadata": {
+                "position": {"x": 0, "y": 0},
+                "input_schema": [
+                    {
+                        "list": False,
+                        "name": "name",
+                        "type": "str",
+                        "required": True,
+                        "description": "user's name",
+                    },
+                    {
+                        "list": False,
+                        "name": "email",
+                        "type": "str",
+                        "required": True,
+                        "description": "user's email",
+                    },
+                ],
+                "metric_properties": [],
+            },
+        },
+        {
+            "id": "node-escalate",
+            "name": "_escalate_conversation",
+            "description": "",
+            "prompt": "",
+            "metadata": {
+                "name": "{trigger.name}",
+                "tags": [],
+                "email": "{trigger.email}",
+                "position": {"x": 546.47, "y": 23.69},
+                "ticket_name": "{trigger.conversation.title}",
+                "escalation_mode": "default",
+                "ticket_priority": None,
+                "should_yield_default_response": False,
+                "append_summary_to_ticket_description": False,
+                "append_transcript_to_ticket_description": False,
+            },
+        },
+    ],
+    "edges": [
+        {
+            "id": "edge-1",
+            "source_node_id": "node-trigger",
+            "target_node_id": "node-escalate",
+            "source_result": None,
+            "target_argument": None,
+            "label": None,
+        }
+    ],
+}
+
+
+def create_escalation_flow(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    timeout_seconds: float = 30.0,
+) -> dict[str, Any]:
+    """Import the silent escalation flow for an email agent and activate it.
+
+    The flow triggers on LLM call and silently escalates the conversation
+    (should_yield_default_response=False) without sending a reply to the customer.
+    """
+    import io
+    import json as _json
+    import uuid as _uuid
+
+    flow_json = _json.dumps(_ESCALATION_FLOW_TEMPLATE).encode("utf-8")
+    filename = f"escalate_conversation_{_uuid.uuid4().hex[:8]}.json"
+
+    # Do NOT set Content-Type — httpx sets it automatically for multipart uploads
+    headers = {
+        "Authorization": f"Bearer {api_token}",
+        "X-Shop-Id": shop_id,
+    }
+    url = f"{base_url}/v1/flows/import/"
+
+    try:
+        resp = httpx.post(
+            url,
+            headers=headers,
+            files={"file": (filename, io.BytesIO(flow_json), "application/json")},
+            data={"agent_id": agent_id},
+            timeout=timeout_seconds,
+        )
+    except httpx.HTTPError as exc:
+        raise APIError(
+            f"Network error creating escalation flow: {exc}",
+            code="NETWORK_ERROR",
+            retryable=True,
+            method="POST",
+            url=url,
+        ) from exc
+
+    if resp.status_code >= 400:
+        detail = _error_detail(resp)
+        raise _build_api_error(method="POST", url=url, status_code=resp.status_code, detail=detail)
+
+    flow_data = resp.json()
+    if not isinstance(flow_data, dict):
+        raise APIError("Escalation flow import response is not an object.")
+
+    flow_id = flow_data.get("id") or flow_data.get("flowId")
+    if not flow_id:
+        raise APIError("Escalation flow import response missing id.")
+
+    # The template embeds "status": "Active" so the flow is usually already active
+    # after import. Attempt activation in case the backend overrides to DRAFT, but
+    # treat any error as non-fatal.
+    try:
+        activate_data = _request_json(
+            method="PATCH",
+            url=f"{base_url}/v1/flows/{flow_id}/",
+            shop_id=shop_id,
+            api_token=api_token,
+            timeout_seconds=timeout_seconds,
+            payload={"status": "active"},
+        )
+        return activate_data if isinstance(activate_data, dict) else flow_data
+    except APIError:
+        # Flow was imported; activation PATCH may fail if already active or
+        # the endpoint requires additional fields. Return import data as-is.
+        return flow_data