zenava 0.3.0__py3-none-any.whl

cli_anything/cticloud/__init__.py

@@ -0,0 +1,4 @@
+"""CTICloud CLI harness for predictive outbound tasks."""
+
+__version__ = "0.3.0"
+__released_on__ = "2026-08-31"

cli_anything/cticloud/__main__.py

@@ -0,0 +1,4 @@
+from cli_anything.cticloud.cticloud_cli import main
+
+if __name__ == "__main__":
+    main()

cli_anything/cticloud/core/agent_action_api.py

@@ -0,0 +1,460 @@
+"""Wiki-aligned models and HTTP for agent Action APIs."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from cli_anything.cticloud.core.client import CtiApiError, CtiCloudInterfaceClient
+from cli_anything.cticloud.core.config import CtiConfig
+
+MAX_REFUSE_DESCRIPTION_LEN = 20
+VALID_PAUSE_TYPES = {1, 2, 3}
+
+
+def _omit_empty(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop None and empty string values."""
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def _check_result(resp: dict, default_msg: str) -> dict:
+    """Raise CtiApiError when platform result is not success."""
+    if str(resp.get("result")) != "0":
+        raise CtiApiError(resp.get("description", default_msg), resp)
+    return resp
+
+
+def validate_cno(cno: str) -> None:
+    """Validate agent id is non-empty."""
+    if not cno or not str(cno).strip():
+        raise ValueError("cno 不能为空")
+
+
+def validate_json_array_string(value: str, field: str) -> None:
+    """Validate value is a JSON array string."""
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{field} 须为合法 JSON 数组") from exc
+    if not isinstance(parsed, list):
+        raise ValueError(f"{field} 须为 JSON 数组")
+
+
+@dataclass
+class AgentLoginParams:
+    """Parameters for GET /agent/login."""
+
+    cno: str
+    bind_tel: str
+    bind_type: int
+    login_status: int = 1
+    pause_description: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+        if not self.bind_tel or not str(self.bind_tel).strip():
+            raise ValueError("bindTel 不能为空")
+
+    def to_api_params(self) -> Dict[str, Any]:
+        """Build camelCase query; loginStatus default always sent."""
+        raw: Dict[str, Any] = {
+            "cno": self.cno,
+            "bindTel": self.bind_tel,
+            "bindType": str(self.bind_type),
+            "loginStatus": str(self.login_status),
+        }
+        if self.pause_description:
+            raw["pauseDescription"] = self.pause_description
+        return raw
+
+
+@dataclass
+class AgentLogoutParams:
+    """Parameters for GET /agent/logout."""
+
+    cno: str
+    remove_binding: int = 0
+    is_kickout: int = 1
+    ignore_offline: int = 0
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        return {
+            "cno": self.cno,
+            "removeBinding": str(self.remove_binding),
+            "isKickout": str(self.is_kickout),
+            "ignoreOffline": str(self.ignore_offline),
+        }
+
+
+@dataclass
+class AgentPauseParams:
+    """Parameters for GET /agent/pause."""
+
+    cno: str
+    type: int
+    description: str
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+        if self.type not in VALID_PAUSE_TYPES:
+            raise ValueError("type 取值不正确")
+        if not self.description or not str(self.description).strip():
+            raise ValueError("description 不能为空")
+
+    def to_api_params(self) -> Dict[str, Any]:
+        return {
+            "cno": self.cno,
+            "type": str(self.type),
+            "description": self.description,
+        }
+
+
+@dataclass
+class AgentUnpauseParams:
+    """Parameters for GET /agent/unpause."""
+
+    cno: str
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        return {"cno": self.cno}
+
+
+@dataclass
+class AgentChangeBindTelParams:
+    """Parameters for GET /agent/changeBindTel."""
+
+    cno: str
+    bind_tel: str
+    bind_type: int
+    is_verify: int = 1
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+        if not self.bind_tel:
+            raise ValueError("bindTel 不能为空")
+
+    def to_api_params(self) -> Dict[str, Any]:
+        return {
+            "cno": self.cno,
+            "bindTel": self.bind_tel,
+            "bindType": str(self.bind_type),
+            "isVerify": str(self.is_verify),
+        }
+
+
+@dataclass
+class AgentUnbindTelParams:
+    """Parameters for GET /agent/unbindAgentTel."""
+
+    cno: str
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        return {"cno": self.cno}
+
+
+@dataclass
+class AgentConsultParams:
+    """Parameters for GET /agent/consult."""
+
+    cno: str
+    object_type: int
+    consult_object: str
+    consult_variables: Optional[str] = None
+    hold_music_class: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+        if not self.consult_object:
+            raise ValueError("consultObject 不能为空")
+        if self.consult_variables:
+            validate_json_array_string(self.consult_variables, "consultVariables")
+
+    def to_api_params(self) -> Dict[str, Any]:
+        raw: Dict[str, Any] = {
+            "cno": self.cno,
+            "objectType": str(self.object_type),
+            "consultObject": self.consult_object,
+        }
+        optional = {
+            "consultVariables": self.consult_variables,
+            "holdMusicClass": self.hold_music_class,
+        }
+        raw.update(optional)
+        return _omit_empty(raw)
+
+
+@dataclass
+class AgentConsultTransferParams:
+    """Parameters for GET /agent/consultTransfer."""
+
+    cno: str
+    limit_time_second: Optional[int] = None
+    limit_time_alert_second: Optional[int] = None
+    limit_time_file: Optional[str] = None
+    is_investigation: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        validate_cno(self.cno)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        raw: Dict[str, Any] = {"cno": self.cno}
+        optional = {
+            "limitTimeSecond": (
+                str(self.limit_time_second) if self.limit_time_second is not None else None
+            ),
+            "limitTimeAlertSecond": (
+                str(self.limit_time_alert_second)
+                if self.limit_time_alert_second is not None
+                else None
+            ),
+            "limitTimeFile": self.limit_time_file,
+            "isInvestigation": (
+                str(self.is_investigation) if self.is_investigation is not None else None
+            ),
+        }
+        raw.update(optional)
+        return _omit_empty(raw)
+
+
+@dataclass
+class AgentInvolveThreewayParams:
+    """Parameters for GET /agent/involveThreeway."""
+
+    unique_id: str
+    object_type: int
+    involve_object: Optional[str] = None
+    dial_timeout: Optional[int] = None
+    dial_strategy: Optional[int] = None
+    conference_mode: int = 0
+    barge_on_answer: int = 0
+    involve_variables: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        validate_involve_threeway_params(self)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        raw: Dict[str, Any] = {
+            "uniqueId": self.unique_id,
+            "objectType": str(self.object_type),
+            "conferenceMode": str(self.conference_mode),
+            "bargeOnAnswer": str(self.barge_on_answer),
+        }
+        optional = {
+            "involveObject": self.involve_object,
+            "dialTimeout": str(self.dial_timeout) if self.dial_timeout is not None else None,
+            "dialStrategy": (
+                str(self.dial_strategy) if self.dial_strategy is not None else None
+            ),
+            "involveVariables": self.involve_variables,
+        }
+        raw.update(optional)
+        return _omit_empty(raw)
+
+
+@dataclass
+class AgentRefuseParams:
+    """Parameters for GET /agent/refuse."""
+
+    cno: str
+    description: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        validate_refuse_params(self)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        raw: Dict[str, Any] = {"cno": self.cno}
+        if self.description:
+            raw["description"] = self.description
+        return raw
+
+
+@dataclass
+class AgentUnlinkParams:
+    """Parameters for GET /agent/unlink."""
+
+    cno: Optional[str] = None
+    unique_id: Optional[str] = None
+    request_unique_id: Optional[str] = None
+    side: int = 1
+
+    def __post_init__(self) -> None:
+        validate_unlink_params(self)
+
+    def to_api_params(self) -> Dict[str, Any]:
+        raw: Dict[str, Any] = {"side": str(self.side)}
+        if self.cno:
+            raw["cno"] = self.cno
+        if self.unique_id:
+            raw["uniqueId"] = self.unique_id
+        if self.request_unique_id:
+            raw["requestUniqueId"] = self.request_unique_id
+        return raw
+
+
+def validate_unlink_params(params: AgentUnlinkParams) -> None:
+    """Exactly one of cno, uniqueId, requestUniqueId must be set."""
+    ids = [params.cno, params.unique_id, params.request_unique_id]
+    set_count = sum(1 for x in ids if x and str(x).strip())
+    if set_count != 1:
+        raise ValueError("cno、uniqueId、requestUniqueId 须恰好指定一个")
+
+
+def validate_involve_threeway_params(params: AgentInvolveThreewayParams) -> None:
+    """Validate involve threeway conditional fields."""
+    if not params.unique_id:
+        raise ValueError("uniqueId 不能为空")
+    if params.object_type in (1, 2) and not params.involve_object:
+        raise ValueError("objectType 为 1 或 2 时 involveObject 不能为空")
+    if params.dial_timeout is not None and not (2 < params.dial_timeout <= 60):
+        raise ValueError("dialTimeout 须在 2–60 之间")
+    if params.involve_variables:
+        validate_json_array_string(params.involve_variables, "involveVariables")
+
+
+def validate_refuse_params(params: AgentRefuseParams) -> None:
+    """Validate refuse description length."""
+    validate_cno(params.cno)
+    if params.description and len(params.description) >= MAX_REFUSE_DESCRIPTION_LEN:
+        raise ValueError(f"description 长度须小于 {MAX_REFUSE_DESCRIPTION_LEN}")
+
+
+def agent_login(
+    config: CtiConfig,
+    params: AgentLoginParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent login (GET /agent/login)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/login", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席上线失败")
+
+
+def agent_logout(
+    config: CtiConfig,
+    params: AgentLogoutParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent logout (GET /agent/logout)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/logout", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席下线失败")
+
+
+def agent_pause(
+    config: CtiConfig,
+    params: AgentPauseParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent pause (GET /agent/pause)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/pause", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席置忙失败")
+
+
+def agent_unpause(
+    config: CtiConfig,
+    params: AgentUnpauseParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent unpause (GET /agent/unpause)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/unpause", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席置闲失败")
+
+
+def agent_change_bind_tel(
+    config: CtiConfig,
+    params: AgentChangeBindTelParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Change bind tel (GET /agent/changeBindTel)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/changeBindTel", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "修改绑定电话失败")
+
+
+def agent_unbind_agent_tel(
+    config: CtiConfig,
+    params: AgentUnbindTelParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Unbind agent tel (GET /agent/unbindAgentTel)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/unbindAgentTel", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "解除绑定电话失败")
+
+
+def agent_consult(
+    config: CtiConfig,
+    params: AgentConsultParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent consult (GET /agent/consult)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/consult", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席咨询失败")
+
+
+def agent_consult_transfer(
+    config: CtiConfig,
+    params: AgentConsultTransferParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Consult transfer (GET /agent/consultTransfer)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/consultTransfer", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席咨询转移失败")
+
+
+def agent_involve_threeway(
+    config: CtiConfig,
+    params: AgentInvolveThreewayParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Involve threeway (GET /agent/involveThreeway)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/involveThreeway", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "邀请三方失败")
+
+
+def agent_refuse(
+    config: CtiConfig,
+    params: AgentRefuseParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent refuse (GET /agent/refuse)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/refuse", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席拒接失败")
+
+
+def agent_unlink(
+    config: CtiConfig,
+    params: AgentUnlinkParams,
+    *,
+    verbose: bool = False,
+) -> Dict[str, Any]:
+    """Agent unlink/hangup (GET /agent/unlink)."""
+    client = CtiCloudInterfaceClient(config)
+    resp = client.get("/agent/unlink", params.to_api_params(), verbose=verbose)
+    return _check_result(resp, "座席挂机失败")

cli_anything/cticloud/core/agent_analysis_config_api.py

@@ -0,0 +1,88 @@
+"""智能体话后分析配置：/cc 融合 OpenAPI 四操作（两平台共用路径，鉴权按平台切换）。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from cli_anything.cticloud.core.agent_analysis_config_params import AgentAnalysisConfigParams
+from cli_anything.cticloud.core.client import CtiApiError, make_cc_client
+from cli_anything.cticloud.core.config import CtiConfig
+from cli_anything.cticloud.core.platform_guard import ensure_command_allowed
+
+# 文档成功形态：delete 返回 result="success"；其余响应无 result 码或为 "0"。
+_SUCCESS_VALUES = {"0", "success"}
+
+
+def _raise_on_error(resp: Dict[str, Any]) -> Dict[str, Any]:
+    """响应含 result 非 0/success，或含 error 对象时抛业务错误；否则原样返回（D9）。
+
+    error 对象形态：{"error": {"code": "InvalidParameter", "message": "…"}}（live-qa 2026-08-18 记录缺口，
+    0.2.8 起判为业务失败 → exit 1）。错误文案取 code+message，不含任何密钥字段（D15）。
+    """
+    if isinstance(resp, dict):
+        error = resp.get("error")
+        if isinstance(error, dict) and error.get("code") is not None and str(error.get("code")) != "success":
+            code = str(error.get("code"))
+            msg = error.get("message") or "业务失败"
+            raise CtiApiError(f"{code}: {msg}", resp)
+        if "result" in resp and str(resp.get("result")) not in _SUCCESS_VALUES:
+            raise CtiApiError(
+                resp.get("description") or resp.get("message") or f"业务失败: {resp.get('result')}", resp
+            )
+    return resp
+
+
+def get_agent_analysis_config(config: CtiConfig, agent_id: str, *, verbose: bool = False) -> Dict[str, Any]:
+    """按 agentId 查询话后分析配置（GET，agentId 走 Query）。
+
+    agentId 不存在时服务端返回 InvalidParameter（error 对象），0.2.8 起判为业务失败（D9）。
+    """
+    ensure_command_allowed(config, "callcenter agent-analysis-config get")
+    if agent_id is None or str(agent_id).strip() == "":
+        raise ValueError("agentId 必填")
+    return _raise_on_error(
+        make_cc_client(config).get(
+            "get_intelligent_agent_analysis_config", {"agentId": agent_id}, verbose=verbose
+        )
+    )
+
+
+def create_agent_analysis_config(
+    config: CtiConfig, params: AgentAnalysisConfigParams, *, verbose: bool = False
+) -> Dict[str, Any]:
+    """整包写入话后分析配置（POST JSON Body，D3）。
+
+    服务端行为：未提供的 Active 按 0、列表按 []；记录不存在时新建配置行、
+    已存在则整包覆盖；不创建、不绑定 IVR。仅用于首次创建或整体替换。
+    botType/category 仅在 create 路径写入（include_toplevel_meta=True）。
+    """
+    ensure_command_allowed(config, "callcenter agent-analysis-config create")
+    body = params.to_api_body()
+    return _raise_on_error(
+        make_cc_client(config).post_json("create_intelligent_agent_analysis_config", body, verbose=verbose)
+    )
+
+
+def update_agent_analysis_config(
+    config: CtiConfig, params: AgentAnalysisConfigParams, *, verbose: bool = False
+) -> Dict[str, Any]:
+    """按 JSON 字段是否出现做局部更新（POST JSON Body，D2）。
+
+    未出现的字段保持库内原值；记录必须已存在，不隐式新建。
+    调用方以 include_toplevel_meta=False 构建 body，botType/category 不写入（服务端忽略）。
+    """
+    ensure_command_allowed(config, "callcenter agent-analysis-config update")
+    body = params.to_api_body(include_toplevel_meta=False)
+    return _raise_on_error(
+        make_cc_client(config).post_json("update_intelligent_agent_analysis_config", body, verbose=verbose)
+    )
+
+
+def delete_agent_analysis_config(config: CtiConfig, agent_id: str, *, verbose: bool = False) -> Dict[str, Any]:
+    """整包清空话后分析配置（POST JSON Body 仅 agentId，不删智能体）。"""
+    ensure_command_allowed(config, "callcenter agent-analysis-config delete")
+    if agent_id is None or str(agent_id).strip() == "":
+        raise ValueError("agentId 必填")
+    return _raise_on_error(
+        make_cc_client(config).post_json("delete_intelligent_agent_analysis_config",
+                                         {"agentId": agent_id}, verbose=verbose)
+    )