rcs-openapi-client 0.5.0__py3-none-any.whl

rcs_openapi/__init__.py

@@ -0,0 +1,43 @@
+"""RCS Open API Python SDK。"""
+
+from .client import RcsOpenApiClient
+from .errors import (
+    PiiDecryptionError,
+    RcsOpenApiError,
+    RcsProtocolError,
+    RcsTransportError,
+    WebhookError,
+)
+from .pii import PiiDecryptor
+from .rules import LeadIntakeRule
+from .types import (
+    CurrentUser,
+    Customer,
+    CustomerInput,
+    CustomField,
+    JsonObject,
+    ListResponse,
+    PartnerBinding,
+)
+from .webhook import WebhookEvent, WebhookReceiver
+
+__version__ = "0.5.0"
+__all__ = [
+    "RcsOpenApiClient",
+    "RcsOpenApiError",
+    "RcsProtocolError",
+    "RcsTransportError",
+    "PiiDecryptor",
+    "PiiDecryptionError",
+    "WebhookReceiver",
+    "WebhookEvent",
+    "WebhookError",
+    "LeadIntakeRule",
+    "CurrentUser",
+    "PartnerBinding",
+    "Customer",
+    "CustomerInput",
+    "CustomField",
+    "JsonObject",
+    "ListResponse",
+]

rcs_openapi/client.py

@@ -0,0 +1,473 @@
+"""同步开放 API 客户端：不自动重试写入、不自动跟随重定向。"""
+
+import base64
+import math
+import re
+from collections.abc import Mapping
+from copy import deepcopy
+from types import TracebackType
+from typing import Any, Self, cast
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from .errors import RcsOpenApiError, RcsProtocolError, RcsTransportError
+from .pii import CUSTOMER_PII_FIELDS, PiiDecryptor
+from .rules import LeadIntakeRule
+from .types import CurrentUser, Customer, JsonObject, ListResponse
+
+
+def _url(value: str, *, base: bool = False) -> str:
+    try:
+        parsed = urlsplit(value)
+        valid = parsed.scheme == "https" or (
+            parsed.scheme == "http" and parsed.hostname in ("localhost", "127.0.0.1", "::1")
+        )
+        if (
+            not valid
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+        ):
+            raise ValueError
+        _ = parsed.port
+        if "#" in value or (base and ("?" in value or parsed.path not in ("", "/"))):
+            raise ValueError
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError(
+            "URL 必须为 HTTPS 根地址（仅本机环回测试允许 HTTP），不得含用户名或密码"
+        ) from None
+    return value.rstrip("/") if base else value
+
+
+def _id(value: str) -> str:
+    if not isinstance(value, str) or not value or value in (".", ".."):
+        raise ValueError("资源 ID 不得为空或相对路径片段")
+    return quote(value, safe="")
+
+
+class RcsOpenApiClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        access_key_id: str | None = None,
+        secret_key: str | None = None,
+        access_token: str | None = None,
+        pii_aes_key: str | None = None,
+        timeout: float = 15,
+        transport: httpx.BaseTransport | None = None,
+        partner_id: str | None = None,
+        partner_client_id: str | None = None,
+        partner_client_secret: str | None = None,
+    ) -> None:
+        self._base_url = _url(base_url, base=True)
+        if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout 必须为正的有限秒数")
+        self._access_key_id = access_key_id
+        self._secret_key = secret_key
+        self._access_token = access_token
+        self._partner_id = partner_id
+        self._partner_client_id = partner_client_id
+        self._partner_client_secret = partner_client_secret
+        self._pii = PiiDecryptor(pii_aes_key) if pii_aes_key is not None else None
+        self._http = httpx.Client(timeout=timeout, transport=transport, follow_redirects=False)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def authenticate(self) -> str:
+        if not self._access_key_id or not self._secret_key:
+            raise ValueError("缺少 access_key_id / secret_key")
+        data = self._request(
+            "POST",
+            "/auth/token",
+            body={"accessKeyId": self._access_key_id, "secretKey": self._secret_key},
+            auth=False,
+        )
+        token = data.get("accessToken")
+        if not isinstance(token, str) or not token:
+            raise RcsProtocolError("换 token 响应缺少有效 accessToken")
+        self._access_token = token
+        return token
+
+    def send_partner_login_sms(self, phone: str) -> JsonObject:
+        """申请合作方验证码，返回 challengeId。"""
+        return self._post_partner_login("/sms/send", {"phone": phone})
+
+    def submit_partner_login(
+        self, input: Mapping[str, Any], idempotency_key: str
+    ) -> JsonObject:
+        """提交密码或短信登录；同一请求重试复用幂等键。"""
+        if not re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", idempotency_key):
+            raise ValueError("幂等键格式不正确")
+        return self._post_partner_login("", input, idempotency_key)
+
+    def exchange_partner_login_code(self, code: str) -> JsonObject:
+        """兑换一次性码；令牌由调用方按用户保存，客户端不自动重试。"""
+        return self._post_partner_login("/exchange", {"code": code})
+
+    def _post_partner_login(
+        self, path: str, body: Mapping[str, Any], idempotency_key: str | None = None
+    ) -> JsonObject:
+        if not self._partner_id or not self._partner_client_id or not self._partner_client_secret:
+            raise ValueError("缺少合作方登录凭证")
+        if urlsplit(self._base_url).scheme != "https":
+            raise ValueError("合作方登录必须使用 HTTPS")
+        basic = base64.b64encode(
+            f"{self._partner_client_id}:{self._partner_client_secret}".encode()
+        ).decode("ascii")
+        headers = {"Authorization": "Basic " + basic}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._request(
+            "POST", "/auth/partner-login" + path,
+            body={**body, "partner_id": self._partner_id}, auth=False, extra_headers=headers,
+        )
+
+    def set_access_token(self, token: str) -> None:
+        if not isinstance(token, str) or not token:
+            raise ValueError("token 不得为空")
+        self._access_token = token
+
+    def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> httpx.Response:
+        try:
+            response = self._http.request(
+                method,
+                url,
+                headers=headers,
+                params=params,
+                json=dict(body) if body is not None else None,
+            )
+        except httpx.RequestError:
+            raise RcsTransportError(
+                "HTTP 请求失败（连接、TLS 或超时）；写入结果可能未知，请先回查"
+            ) from None
+        if 300 <= response.status_code < 400:
+            raise RcsProtocolError("接口返回意外重定向，SDK 未跟随")
+        return response
+
+    @staticmethod
+    def _error(response: httpx.Response) -> RcsOpenApiError:
+        try:
+            data = response.json()
+            error = data.get("error", {}) if isinstance(data, dict) else {}
+            if not isinstance(error, dict):
+                error = {}
+        except ValueError:
+            error = {}
+        code = error.get("code")
+        message = error.get("message")
+        return RcsOpenApiError(
+            code if isinstance(code, str) else "unknown",
+            message if isinstance(message, str) else "接口请求失败",
+            response.status_code,
+            request_id=error.get("requestId") if isinstance(error.get("requestId"), str) else None,
+            details=error.get("details"),
+            retryable=error.get("retryable") if isinstance(error.get("retryable"), bool) else None,
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        *,
+        auth: bool = True,
+        existing_lead: bool = False,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> JsonObject:
+        headers = {"Accept": "application/json", **(extra_headers or {})}
+        if auth:
+            if not self._access_token:
+                raise ValueError("未鉴权：请先 authenticate() 或传入 access_token")
+            headers["Authorization"] = "Bearer " + self._access_token
+        query = {
+            k: str(v).lower() if isinstance(v, bool) else v
+            for k, v in (params or {}).items()
+            if v is not None and v != ""
+        }
+        response = self._send(
+            method, self._base_url + "/api/open/v1" + path, headers=headers, params=query, body=body
+        )
+        if response.status_code == 204:
+            return {}
+        try:
+            data = response.json()
+        except ValueError:
+            if response.is_error:
+                raise self._error(response) from None
+            raise RcsProtocolError("接口成功响应不是有效 JSON 对象") from None
+        if response.is_error:
+            if (
+                existing_lead
+                and response.status_code == 409
+                and isinstance(data, dict)
+                and isinstance(data.get("leadId"), str)
+                and data["leadId"]
+                and data.get("alreadyExisted") is True
+            ):
+                return cast(JsonObject, data)
+            raise self._error(response)
+        if not isinstance(data, dict):
+            raise RcsProtocolError("接口成功响应必须是 JSON 对象")
+        return cast(JsonObject, data)
+
+    def create_outbound_call(self, input: Mapping[str, Any]) -> JsonObject:
+        """提交任务；externalRef 由调用方提供，不自动重试或替换。"""
+        return self._request("POST", "/outbound-calls", body=input)
+
+    def get_outbound_call_task(self, task_id: str) -> JsonObject:
+        return self._request("GET", "/outbound-calls/" + _id(task_id))
+
+    def list_outbound_calls(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/outbound-calls", params)
+
+    def list_customers(self, params: Mapping[str, Any] | None = None) -> ListResponse[Customer]:
+        return cast(ListResponse[Customer], self._request("GET", "/customers", params))
+
+    def get_current_user(self) -> CurrentUser:
+        """获取当前令牌对应的用户资料及适用的合作方绑定。"""
+        return cast(CurrentUser, self._request("GET", "/users/me"))
+
+    def get_customer(self, id: str) -> Customer:
+        return cast(Customer, self._request("GET", "/customers/" + _id(id)))
+
+    def create_customer(self, input: Mapping[str, Any]) -> Customer:
+        return cast(Customer, self._request("POST", "/customers", body=input))
+
+    def update_customer(self, id: str, patch: Mapping[str, Any]) -> Customer:
+        return cast(Customer, self._request("PATCH", "/customers/" + _id(id), body=patch))
+
+    def list_customer_fields(self) -> JsonObject:
+        return self._request("GET", "/customer-fields")
+
+    def set_do_not_disturb(
+        self, id: str, do_not_disturb: bool, reason: str | None = None
+    ) -> Customer:
+        if not isinstance(do_not_disturb, bool):
+            raise ValueError("do_not_disturb 必须是布尔值")
+        body: JsonObject = {"doNotDisturb": do_not_disturb}
+        if do_not_disturb:
+            if not isinstance(reason, str) or not reason.strip():
+                raise ValueError("开启免打扰必须提供原因")
+            body["dndReason"] = reason
+        return self.update_customer(id, body)
+
+    def list_agents(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/agents", params)
+
+    def get_agent(self, id: str) -> JsonObject:
+        return self._request("GET", "/agents/" + _id(id))
+
+    def create_agent(self, input: Mapping[str, Any]) -> JsonObject:
+        """创建主体，必填 aliasName、storeAddress、entityType、name。"""
+        return self._request("POST", "/agents", body=input)
+
+    def delete_agent(self, id: str) -> None:
+        """归档主体，未结束的营销计划引用时保留服务端 409。"""
+        self._request("DELETE", "/agents/" + _id(id))
+
+    def update_agent(self, id: str, patch: Mapping[str, Any]) -> JsonObject:
+        return self._request("PATCH", "/agents/" + _id(id), body=patch)
+
+    def list_campaigns(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/campaigns", params)
+
+    def get_campaign(self, id: str) -> JsonObject:
+        return self._request("GET", "/campaigns/" + _id(id))
+
+    def create_campaign(self, input: Mapping[str, Any]) -> JsonObject:
+        return self._request("POST", "/campaigns", body=input)
+
+    def update_campaign(self, id: str, patch: Mapping[str, Any]) -> JsonObject:
+        return self._request("PATCH", "/campaigns/" + _id(id), body=patch)
+
+    def rename_campaign(self, id: str, name: str) -> JsonObject:
+        return self.update_campaign(id, {"name": name})
+
+    def set_campaign_status(self, id: str, target: str) -> JsonObject:
+        return self.update_campaign(id, {"status": target})
+
+    def set_campaign_lead_intake_rule(
+        self, id: str, lead_intake_rule: Mapping[str, Any] | list[dict[str, Any]]
+    ) -> JsonObject:
+        rules = (
+            lead_intake_rule.get("rules")
+            if isinstance(lead_intake_rule, Mapping)
+            else lead_intake_rule
+        )
+        if not isinstance(rules, list):
+            raise ValueError("leadIntakeRule.rules 必须为数组")
+        return self.update_campaign(id, {"leadIntakeRule": LeadIntakeRule.rules(*rules)})
+
+    def reset_campaign_lead_intake_rule(self, id: str) -> JsonObject:
+        return self.update_campaign(id, {"leadIntakeRule": None})
+
+    def delete_campaign(self, id: str) -> None:
+        self._request("DELETE", "/campaigns/" + _id(id))
+
+    def list_scenarios(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/scenarios", params)
+
+    def get_scenario(self, id: str) -> JsonObject:
+        return self._request("GET", "/scenarios/" + _id(id))
+
+    def create_scenario(self, name: str, template_alias: str) -> JsonObject:
+        return self._request(
+            "POST", "/scenarios", body={"name": name, "templateAlias": template_alias}
+        )
+
+    def rename_scenario(self, id: str, name: str) -> JsonObject:
+        return self._request("PATCH", "/scenarios/" + _id(id), body={"name": name})
+
+    def delete_scenario(self, id: str) -> None:
+        self._request("DELETE", "/scenarios/" + _id(id))
+
+    def test_dial(
+        self,
+        phone: str,
+        scenario_name: str | None = None,
+        scenario_template_alias: str | None = None,
+    ) -> JsonObject:
+        if (scenario_name is None) == (scenario_template_alias is None):
+            raise ValueError("scenario_name 与 scenario_template_alias 必须且只能提供一个")
+        body = {"phone": phone}
+        if scenario_name is not None:
+            body["scenarioName"] = scenario_name
+        if scenario_template_alias is not None:
+            body["scenarioTemplateAlias"] = scenario_template_alias
+        return self._request("POST", "/calls/test-dial", body=body)
+
+    def list_call_records(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/call-records", params)
+
+    def get_call_record(self, id: str) -> JsonObject:
+        return self._request("GET", "/call-records/" + _id(id))
+
+    def list_campaign_rounds(
+        self, campaign_id: str, params: Mapping[str, Any] | None = None
+    ) -> JsonObject:
+        return self._request("GET", "/campaigns/" + _id(campaign_id) + "/rounds", params)
+
+    def get_campaign_round(
+        self, campaign_id: str, round_id: str, params: Mapping[str, Any] | None = None
+    ) -> JsonObject:
+        return self._request(
+            "GET", "/campaigns/" + _id(campaign_id) + "/rounds/" + _id(round_id), params
+        )
+
+    def list_devices(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/devices", params)
+
+    def get_device(self, id: str) -> JsonObject:
+        return self._request("GET", "/devices/" + _id(id))
+
+    def update_sim_quota(self, device_id: str, sim_id: str, quota: Mapping[str, Any]) -> JsonObject:
+        return self._request(
+            "PATCH", "/devices/" + _id(device_id) + "/sims/" + _id(sim_id) + "/quota", body=quota
+        )
+
+    def update_sim_phone_number(self, device_id: str, sim_id: str, phone_number: str) -> JsonObject:
+        if not isinstance(phone_number, str) or (
+            phone_number.strip() and not re.fullmatch(r"\+?[0-9]{3,20}", phone_number.strip())
+        ):
+            raise ValueError("SIM 号码必须是3–20位数字（可带+），或空串清除")
+        return self._request(
+            "PATCH",
+            "/devices/" + _id(device_id) + "/sims/" + _id(sim_id) + "/phone",
+            body={"phoneNumber": phone_number.strip()},
+        )
+
+    def clear_sim_phone_number(self, device_id: str, sim_id: str) -> JsonObject:
+        return self.update_sim_phone_number(device_id, sim_id, "")
+
+    def list_marketing_leads(self, params: Mapping[str, Any] | None = None) -> JsonObject:
+        return self._request("GET", "/marketing-leads", params)
+
+    def get_marketing_lead(self, id: str) -> JsonObject:
+        return self._request("GET", "/marketing-leads/" + _id(id))
+
+    def create_lead_from_call(self, body: Mapping[str, Any]) -> JsonObject:
+        return self._request("POST", "/marketing-leads/from-call", body=body, existing_lead=True)
+
+    def update_marketing_lead(self, id: str, patch: Mapping[str, Any]) -> JsonObject:
+        return self._request("PATCH", "/marketing-leads/" + _id(id), body=patch)
+
+    def delete_marketing_lead(self, id: str) -> None:
+        self._request("DELETE", "/marketing-leads/" + _id(id))
+
+    def get_outbound_daily_stats(self, date: str | None = None) -> JsonObject:
+        return self._request("GET", "/stats/outbound-daily", {"date": date})
+
+    def get_scenario_summary(
+        self,
+        start_date: str,
+        end_date: str,
+        *,
+        scenario_id: str | None = None,
+        scenario_alias: str | None = None,
+    ) -> JsonObject:
+        """Sum stored daily statistics (inclusive dates; no live recalculation)."""
+        return self._request(
+            "GET",
+            "/stats/scenario-summary",
+            {
+                "startDate": start_date,
+                "endDate": end_date,
+                "scenarioId": scenario_id,
+                "scenarioAlias": scenario_alias,
+            },
+        )
+
+    def fetch_recording(self, recording_url: str) -> bytes:
+        response = self._send("GET", _url(recording_url))
+        if response.is_error:
+            raise self._error(response)
+        return response.content
+
+    def decrypt_pii(self, encoded: str | None) -> str | None:
+        if encoded is None:
+            return None
+        if self._pii is None:
+            raise ValueError("未配置 pii_aes_key，无法解密")
+        return self._pii.decrypt(encoded)
+
+    def decrypt_customer(self, customer: Mapping[str, Any]) -> Customer:
+        result = deepcopy(dict(customer))
+        for field in CUSTOMER_PII_FIELDS:
+            if field in result:
+                result[field] = self.decrypt_pii(result[field])
+        return cast(Customer, result)
+
+    def decrypt_call_record(self, record: Mapping[str, Any]) -> JsonObject:
+        result = deepcopy(dict(record))
+        if "phoneNumber" in result:
+            result["phoneNumber"] = self.decrypt_pii(result["phoneNumber"])
+        return result
+
+    def decrypt_marketing_lead(self, lead: Mapping[str, Any]) -> JsonObject:
+        result = deepcopy(dict(lead))
+        if isinstance(result.get("customer"), dict):
+            result["customer"] = self.decrypt_customer(result["customer"])
+        return result

rcs_openapi/errors.py

@@ -0,0 +1,37 @@
+"""不在传输异常中暴露凭据、签名 URL 或原始响应正文。"""
+
+from typing import Any
+
+
+class RcsOpenApiError(Exception):
+    """服务端业务错误；status/code 可直接用于调用方分支处理。"""
+
+    def __init__(
+        self, code: str, message: str, status: int, *,
+        request_id: str | None = None, details: Any = None, retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.details = details
+        self.retryable = retryable
+
+
+class RcsTransportError(Exception):
+    """连接、TLS 或超时失败；写操作的最终执行状态可能未知。"""
+
+
+class RcsProtocolError(Exception):
+    """意外重定向、响应形状或 JSON 不符合接口约定。"""
+
+
+class PiiDecryptionError(ValueError):
+    """PII 密文无效、密钥不匹配或认证失败。"""
+
+
+class WebhookError(ValueError):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code

rcs_openapi/pii.py

@@ -0,0 +1,59 @@
+"""enc:v1: 的 AES-256-GCM 解密，与 PHP/TypeScript SDK 共用字节格式。"""
+
+import base64
+import binascii
+import re
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .errors import PiiDecryptionError
+
+CUSTOMER_PII_FIELDS = ("phoneNumber", "name", "address", "licensePlate")
+
+
+class PiiDecryptor:
+    def __init__(self, pii_aes_key: str) -> None:
+        self._aes = AESGCM(self.parse_key(pii_aes_key))
+
+    @staticmethod
+    def parse_key(raw: str) -> bytes:
+        if not isinstance(raw, str):
+            raise ValueError("PII 密钥必须为 hex64 或 base64 字符串")
+        text = raw.strip()
+        try:
+            key = (
+                bytes.fromhex(text)
+                if re.fullmatch(r"[0-9a-fA-F]{64}", text)
+                else base64.b64decode(text, validate=True)
+            )
+        except (ValueError, binascii.Error):
+            raise ValueError("PII 密钥必须为32字节（hex64 或 base64）") from None
+        if len(key) != 32:
+            raise ValueError("PII 密钥必须为32字节（hex64 或 base64）")
+        return key
+
+    def decrypt(self, encoded: str | None) -> str | None:
+        if encoded is None:
+            return None
+        if not isinstance(encoded, str):
+            raise PiiDecryptionError("PII 字段必须是字符串或 None")
+        if not encoded.startswith("enc:v1:"):
+            return encoded
+        try:
+            raw = base64.b64decode(encoded[7:], validate=True)
+            if len(raw) < 28:
+                raise ValueError("short ciphertext")
+            return self._aes.decrypt(raw[:12], raw[12:], None).decode("utf-8")
+        except (ValueError, binascii.Error, InvalidTag, UnicodeError):
+            raise PiiDecryptionError("PII 解密失败：密文无效或密钥不匹配") from None
+
+    def decrypt_fields(self, obj: Mapping[str, Any], fields: Sequence[str]) -> dict[str, Any]:
+        result = deepcopy(dict(obj))
+        for field in fields:
+            if field in result:
+                result[field] = self.decrypt(result[field])
+        return result

rcs_openapi/rules.py

@@ -0,0 +1,99 @@
+"""线索纳入规则构造器；fieldKey 是否存在仍由服务端按场景校验。"""
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+
+class LeadIntakeRule:
+    OUTCOMES = ("success", "failure", "pending", "no_effective_communication")
+    CONDITION_MODES = ("none", "or", "and")
+    BUILTIN_FIELDS = ("actionResult", "followup", "summary")
+    BUILTIN_OPERATORS = ("includes", "excludes")
+    EXTRACT_OPERATORS = ("includes", "excludes", "equals", "notEquals")
+    MAX_RULES = 50
+    MAX_CONDITIONS = 20
+
+    @classmethod
+    def rules(cls, *rules: Mapping[str, Any]) -> dict[str, Any]:
+        if not 1 <= len(rules) <= cls.MAX_RULES:
+            raise ValueError("leadIntakeRule 必须有 1–50 条规则；恢复默认请用 reset 方法")
+        for rule in rules:
+            cls._validate_rule(rule)
+        return {"rules": deepcopy([dict(rule) for rule in rules])}
+
+    @classmethod
+    def rule(
+        cls,
+        outcome: str,
+        condition_mode: str = "none",
+        conditions: list[dict[str, Any]] | None = None,
+        enabled: bool = True,
+    ) -> dict[str, Any]:
+        result = {
+            "enabled": enabled,
+            "outcome": outcome,
+            "conditionMode": condition_mode,
+            "conditions": [] if conditions is None else deepcopy(conditions),
+        }
+        cls._validate_rule(result)
+        return result
+
+    @classmethod
+    def builtin(cls, field: str, operator: str, keyword: str) -> dict[str, Any]:
+        condition = {"source": "builtin", "field": field, "operator": operator, "keyword": keyword}
+        cls._validate_condition(condition)
+        return condition
+
+    @classmethod
+    def extract(cls, field_key: str, operator: str, keyword: str) -> dict[str, Any]:
+        condition = {
+            "source": "extract",
+            "fieldKey": field_key,
+            "operator": operator,
+            "keyword": keyword,
+        }
+        cls._validate_condition(condition)
+        return condition
+
+    @classmethod
+    def _validate_rule(cls, rule: Mapping[str, Any]) -> None:
+        if not isinstance(rule, Mapping) or rule.get("outcome") not in cls.OUTCOMES:
+            raise ValueError("规则 outcome 取值非法")
+        mode = rule.get("conditionMode", "none")
+        if mode not in cls.CONDITION_MODES:
+            raise ValueError("规则 conditionMode 取值非法")
+        conditions = rule.get("conditions", [])
+        if not isinstance(conditions, list) or len(conditions) > cls.MAX_CONDITIONS:
+            raise ValueError("conditions 必须是最多20项的数组")
+        if (mode == "none" and conditions) or (mode != "none" and not conditions):
+            raise ValueError("none 不得带条件；or/and 至少一个条件")
+        if "enabled" in rule and not isinstance(rule["enabled"], bool):
+            raise ValueError("enabled 必须是布尔值")
+        for condition in conditions:
+            cls._validate_condition(condition)
+
+    @classmethod
+    def _validate_condition(cls, condition: Mapping[str, Any]) -> None:
+        if not isinstance(condition, Mapping):
+            raise ValueError("条件必须为对象")
+        keyword = condition.get("keyword")
+        if not isinstance(keyword, str) or not keyword.replace(",", "").strip():
+            raise ValueError("keyword 必须包含非空关键词")
+        source = condition.get("source", "builtin")
+        if source == "builtin":
+            if (
+                condition.get("field") not in cls.BUILTIN_FIELDS
+                or condition.get("operator") not in cls.BUILTIN_OPERATORS
+            ):
+                raise ValueError("内置条件 field/operator 非法")
+        elif source == "extract":
+            key = condition.get("fieldKey")
+            if (
+                not isinstance(key, str)
+                or not key.strip()
+                or condition.get("operator") not in cls.EXTRACT_OPERATORS
+            ):
+                raise ValueError("提取条件 fieldKey/operator 非法")
+        else:
+            raise ValueError("条件 source 非法")

rcs_openapi/types.py

@@ -0,0 +1,82 @@
+"""JSON 字段采用服务端 camelCase；未知响应字段仍原样保留。"""
+
+from typing import Any, Generic, NotRequired, TypeAlias, TypedDict, TypeVar
+
+JsonObject: TypeAlias = dict[str, Any]
+T = TypeVar("T")
+
+
+class ListResponse(TypedDict, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    pageSize: int
+
+
+class CustomField(TypedDict):
+    fieldKey: str
+    label: str
+    value: Any
+
+
+class PartnerBinding(TypedDict):
+    id: str
+    partnerId: str
+    externalMerchantId: str
+    externalUserId: str
+
+
+class CurrentUser(TypedDict):
+    id: str
+    username: str | None
+    phone: str | None
+    phoneVerified: bool
+    name: str
+    email: str | None
+    company: str | None
+    partnerBinding: PartnerBinding | None
+
+
+class Customer(TypedDict):
+    id: str
+    phoneNumber: str
+    name: str
+    status: str
+    userId: NotRequired[str | None]
+    age: NotRequired[str | None]
+    title: NotRequired[str | None]
+    purchasedServices: NotRequired[str | None]
+    notes: NotRequired[str | None]
+    gender: NotRequired[str | None]
+    source: NotRequired[str | None]
+    intentLevel: NotRequired[str | None]
+    totalCalls: NotRequired[int]
+    lastContactAt: NotRequired[str | None]
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+    externalData: NotRequired[dict[str, Any] | None]
+    debug_info: NotRequired[dict[str, str]]
+    dndSetAt: NotRequired[str | None]
+    address: NotRequired[str | None]
+    licensePlate: NotRequired[str | None]
+    tags: NotRequired[list[str]]
+    customFields: NotRequired[list[CustomField]]
+    doNotDisturb: NotRequired[bool]
+    dndReason: NotRequired[str | None]
+
+
+class CustomerInput(TypedDict, total=False):
+    phoneNumber: str
+    name: str
+    title: str | None
+    purchasedServices: str | None
+    notes: str | None
+    gender: str | None
+    age: int | None
+    address: str | None
+    licensePlate: str | None
+    source: str | None
+    tags: list[str]
+    customFields: dict[str, Any]
+    doNotDisturb: bool
+    dndReason: str | None

rcs_openapi/webhook.py

@@ -0,0 +1,241 @@
+"""框架无关的原始请求体验签；持久化事件 ID 去重由接收方负责。"""
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from datetime import datetime
+from typing import Any
+
+from .errors import WebhookError
+from .pii import CUSTOMER_PII_FIELDS, PiiDecryptor
+from .types import JsonObject
+
+
+class WebhookEvent:
+    def __init__(self, envelope: Mapping[str, Any], pii: PiiDecryptor | None = None) -> None:
+        self._envelope = deepcopy(dict(envelope))
+        self._pii = pii
+
+    @property
+    def envelope(self) -> JsonObject:
+        return deepcopy(self._envelope)
+
+    @property
+    def id(self) -> str:
+        return str(self._envelope["id"])
+
+    @property
+    def type(self) -> str:
+        return str(self._envelope["type"])
+
+    @property
+    def api_version(self) -> str:
+        return str(self._envelope.get("apiVersion", ""))
+
+    @property
+    def occurred_at(self) -> str:
+        return str(self._envelope.get("occurredAt", ""))
+
+    @property
+    def user_id(self) -> str:
+        account = self._envelope.get("account")
+        return str(account.get("userId", "")) if isinstance(account, dict) else ""
+
+    @property
+    def data(self) -> JsonObject:
+        data = self._envelope.get("data")
+        return deepcopy(data) if isinstance(data, dict) else {}
+
+    def is_outbound_call_finished(self) -> bool:
+        return self.type == "outbound_call.finished"
+
+    def outbound_call_task(self) -> JsonObject | None:
+        """结束任务快照；数据仍遵循服务端当前权限与 PII 加密规则。"""
+        task = self.data.get("task")
+        return task if self.is_outbound_call_finished() and isinstance(task, dict) else None
+
+    def is_lead_created(self) -> bool:
+        return self.type == "lead.created"
+
+    def is_device_offline(self) -> bool:
+        return self.type == "device.offline"
+
+    def is_device_alarm(self) -> bool:
+        return self.type == "device.alarm"
+
+    def is_sim_registered(self) -> bool:
+        return self.type == "sim.registered"
+
+    def lead(self) -> JsonObject | None:
+        lead = self.data.get("lead")
+        return lead if self.is_lead_created() and isinstance(lead, dict) else None
+
+    def decrypted_lead(self) -> JsonObject | None:
+        lead = self.lead()
+        if lead is not None and isinstance(lead.get("customer"), dict):
+            if self._pii is None:
+                raise ValueError("未配置 pii_aes_key，无法解密线索 PII")
+            lead["customer"] = self._pii.decrypt_fields(lead["customer"], CUSTOMER_PII_FIELDS)
+        return lead
+
+    def device(self) -> JsonObject | None:
+        device = self.data.get("device")
+        return (
+            device
+            if self.type in ("device.offline", "device.alarm", "sim.registered")
+            and isinstance(device, dict)
+            else None
+        )
+
+    def sim_registered(self) -> JsonObject | None:
+        if not self.is_sim_registered():
+            return None
+        data = self.data
+        sim = data.get("sim")
+        return {
+            "device": self.device(),
+            "sim": sim if isinstance(sim, dict) else None,
+            "registeredAt": data.get("registeredAt"),
+        }
+
+    def offline(self) -> JsonObject | None:
+        if not self.is_device_offline():
+            return None
+        data = self.data
+        return {
+            "device": self.device(),
+            "offlineAt": data.get("offlineAt"),
+            "reason": data.get("reason"),
+        }
+
+    def alarm(self) -> JsonObject | None:
+        if not self.is_device_alarm():
+            return None
+        alarm = self.data.get("alarm")
+        return alarm if isinstance(alarm, dict) else None
+
+
+class WebhookReceiver:
+    def __init__(
+        self, secret: str, *, pii_aes_key: str | None = None, tolerance_seconds: int = 300
+    ) -> None:
+        if not isinstance(secret, str) or not secret:
+            raise ValueError("缺少 webhook secret")
+        if (
+            isinstance(tolerance_seconds, bool)
+            or not isinstance(tolerance_seconds, int)
+            or tolerance_seconds < 0
+        ):
+            raise ValueError("tolerance_seconds 必须为非负整数")
+        self._secret = secret.encode("utf-8")
+        self._tolerance = tolerance_seconds
+        self._pii = PiiDecryptor(pii_aes_key) if pii_aes_key is not None else None
+
+    @staticmethod
+    def _raw(raw_body: bytes | str) -> bytes:
+        if isinstance(raw_body, str):
+            return raw_body.encode("utf-8")
+        if not isinstance(raw_body, bytes):
+            raise WebhookError("invalid_body", "需要原始请求体 bytes 或 str")
+        return raw_body
+
+    def verify_signature(
+        self, raw_body: bytes | str, timestamp: str, signature_header: str
+    ) -> bool:
+        signature = signature_header.removeprefix("v1=").strip()
+        if not re.fullmatch(r"[0-9a-fA-F]{64}", signature):
+            return False
+        expected = hmac.new(
+            self._secret, timestamp.encode("utf-8") + b"." + self._raw(raw_body), hashlib.sha256
+        ).hexdigest()
+        return hmac.compare_digest(expected, signature.lower())
+
+    def check_timestamp(self, timestamp: str, now: int | float | None = None) -> bool:
+        if not re.fullmatch(r"[0-9]{1,20}", timestamp):
+            return False
+        return abs((time.time() if now is None else now) - int(timestamp)) <= self._tolerance
+
+    def parse(
+        self,
+        raw_body: bytes | str,
+        headers: Mapping[str, str | Sequence[str]],
+        *,
+        now: int | float | None = None,
+    ) -> WebhookEvent:
+        normalized: dict[str, str] = {}
+        for key, value in headers.items():
+            name = key.lower()
+            if name not in ("x-rcs-webhook-timestamp", "x-rcs-webhook-signature"):
+                continue
+            if name in normalized:
+                raise WebhookError("invalid_header", "重复的验签请求头")
+            if not isinstance(value, str):
+                if len(value) != 1 or not isinstance(value[0], str):
+                    raise WebhookError("invalid_header", "验签请求头必须具有唯一值")
+                value = value[0]
+            normalized[name] = value
+        timestamp = normalized.get("x-rcs-webhook-timestamp", "")
+        signature = normalized.get("x-rcs-webhook-signature", "")
+        if not timestamp or not signature:
+            raise WebhookError("missing_header", "缺少 Webhook 时间戳或签名头")
+        raw = self._raw(raw_body)
+        if not self.verify_signature(raw, timestamp, signature):
+            raise WebhookError("bad_signature", "Webhook 签名校验失败")
+        if not self.check_timestamp(timestamp, now):
+            raise WebhookError("stale_timestamp", "Webhook 时间戳超出容忍窗口")
+        try:
+            envelope = json.loads(raw)
+        except (ValueError, UnicodeError):
+            raise WebhookError("invalid_body", "Webhook 请求体不是有效 JSON") from None
+        if not isinstance(envelope, dict) or any(
+            not isinstance(envelope.get(field), str) or not envelope[field]
+            for field in ("id", "type")
+        ):
+            raise WebhookError("invalid_body", "Webhook 信封缺少有效 id/type")
+        return WebhookEvent(envelope, self._pii)
+
+
+    def parse_partner_login(
+        self, raw_body: bytes | str, headers: Mapping[str, str], *, now: int | float | None = None
+    ) -> JsonObject:
+        """验证独立的合作方登录结果信封。按 eventId 去重由调用方负责。"""
+        normalized = {name.lower(): value for name, value in headers.items()}
+        timestamp = normalized.get("x-rcs-webhook-timestamp", "")
+        signature = normalized.get("x-rcs-webhook-signature", "")
+        event_id = normalized.get("x-rcs-webhook-id", "")
+        raw = self._raw(raw_body)
+        if (
+            not re.fullmatch(r"[0-9]{10}", timestamp)
+            or not re.fullmatch(r"v1=[0-9a-fA-F]{64}", signature)
+            or not self.check_timestamp(timestamp, now)
+            or not self.verify_signature(raw, timestamp, signature)
+        ):
+            raise WebhookError("bad_signature", "合作方登录回调验签失败")
+        try:
+            event = json.loads(raw)
+        except (ValueError, UnicodeError):
+            raise WebhookError("invalid_body", "合作方登录回调不是有效 JSON") from None
+        if (
+            not isinstance(event, dict) or event.get("event") != "open_api.login.result"
+            or type(event.get("version")) is not int or event["version"] != 1
+            or not event_id or event.get("eventId") != event_id or event.get("requestId") != event_id
+            or not isinstance(event.get("partner_id"), str) or not event["partner_id"]
+        ):
+            raise WebhookError("invalid_body", "合作方登录回调信封无效")
+        status = event.get("status")
+        error = event.get("error")
+        if status == "succeeded" and isinstance(event.get("code"), str) and event["code"]:
+            expires_at = event.get("expiresAt")
+            if isinstance(expires_at, str):
+                try:
+                    datetime.fromisoformat(expires_at)
+                    return event
+                except ValueError:
+                    pass
+        if status == "failed" and isinstance(error, dict) and error.get("code") == "INVALID_LOGIN":
+            return event
+        raise WebhookError("invalid_body", "合作方登录回调结果无效")

rcs_openapi_client-0.5.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: rcs-openapi-client
+Version: 0.5.0
+Summary: RCS 开放 API Python SDK：AK/SK、客户读写、业务接口、PII 解密及 Webhook 验签
+Author: Akimimi
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://gitee.com/akimimi/rcs-openapi-python-client
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: cryptography>=43
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Dynamic: license-file
+
+# RCS Open API Python SDK
+
+Python 3.11+ 的同步客户端，面向 RCS 已上线开放 API。覆盖 PHP SDK 1.11.0 的全部公开能力，并提供客户字段定义读取、类型提示、PII 解密和 Webhook 验签。
+
+生产 API 基址为 `https://vas-api.akimimi.com`。`base_url` 只填根地址，SDK 自动追加 `/api/open/v1`。调用范围由 AK/SK 绑定的普通用户账号决定；IP 白名单由服务端管理员配置。
+
+## 安装
+
+包名 `rcs-openapi-client`，导入名 `rcs_openapi`，当前版本 `0.4.0`。通过私有 Gitee 发行版和构建包分发。
+
+```bash
+# 安装取得的 wheel
+python -m pip install ./rcs_openapi_client-0.4.0-py3-none-any.whl
+
+# 或安装私有仓库的固定版本（需先配置自己的 SSH 访问权限）
+python -m pip install 'git+ssh://git@gitee.com/akimimi/rcs-openapi-python-client.git@v0.4.0'
+```
+
+开发分支示例可用 `@feature/python-sdk`，生产请固定审核通过的提交或发布版本，避免跟随可变分支。依赖为 HTTPX 与 cryptography，由 pip 自动安装。默认遵守 HTTPX 代理和 CA 环境设置；若使用 SOCKS 代理，另外安装 `httpx[socks]`。SDK 保持 TLS 验证开启，不提供跳过证书校验的快捷开关。
+
+## 获取 token、创建和编辑客户
+
+管理员发放两类不同用途的密钥：AK/SK 用来换取 72 小时 Bearer token，PII AES 密钥用来在本地解密响应中的姓名、手机号、地址和车牌。PII 密钥接受32字节的 hex64 或 base64 字符串。
+
+```python
+import os
+from rcs_openapi import RcsOpenApiClient
+
+with RcsOpenApiClient(
+    base_url="https://vas-api.akimimi.com",
+    access_key_id=os.environ["RCS_ACCESS_KEY_ID"],
+    secret_key=os.environ["RCS_SECRET_KEY"],
+    pii_aes_key=os.environ["RCS_PII_AES_KEY"],
+    timeout=15,
+) as client:
+    client.authenticate()  # 缓存在当前实例中；不要写入日志
+    customer = client.create_customer({
+        "phoneNumber": "13800000000",
+        "name": "张三",
+        "age": 35,
+        "licensePlate": "沪A12345",
+        "tags": ["老客户"],
+    })
+    # customer 的 PII 字段仍是 enc:v1: 密文；原响应不会被解密函数修改。
+    plain = client.decrypt_customer(customer)
+    updated = client.update_customer(customer["id"], {
+        "notes": "资料已更新",
+        "licensePlate": None,
+        "tags": [],
+        "doNotDisturb": True,
+        "dndReason": "客户要求停止联系",
+    })
+    detail = client.get_customer(customer["id"])
+    page = client.list_customers({"q": "13800000000", "page": 1, "pageSize": 20})
+```
+
+本段示例会真实创建、编辑客户；请换成已获授权的业务数据。完整脚本见 [examples/customer_flow.py](examples/customer_flow.py)，不会打印密钥或 token。
+
+- SDK 方法使用 snake_case；请求/响应 JSON 字段仍为服务端 camelCase。
+- 创建时 `phoneNumber`、`name` 必填；客户归属由凭据决定，不能伪造 `tenantId`/`userId`。
+- PATCH 仅修改提供的字段；`None` 清空可空字段，`tags=[]` 清空标签，未提供字段保持不变。客户 `age` 输入是整数或 `None`，响应按服务端历史格式为字符串或 `None`。
+- 客户创建与编辑均支持 `customFields`。先用 `list_customer_fields()` 获取定义；键可用中文 label 或 fieldKey，值按定义类型传入，`None` 清空单项。日期通常输入 `YYYY-MM-DD`，返回值按服务端归一化为 ISO 字符串。
+- 列表方法返回服务端分页对象；SDK 不自动遍历所有页。查询布尔值会正确编码为 `true/false`，保留 `False` 和 `0`，忽略 `None` 和空字符串。
+- 可直接传 `access_token=...` 或调用 `set_access_token(...)`；token 到期后再次 `authenticate()`。SDK 不会自动重放写请求。
+- 使用 `with` 管理 HTTP 连接；长期客户端在服务关闭时调用 `close()`。
+
+## 其它已上线接口
+
+[完整 PHP/Python 方法对照](docs/api-parity.md) 包含主体、营销计划及轮次、场景、通话记录、设备与 SIM 配额/号码、营销线索、账号日统计、测试拨号和录音下载。返回 JSON 对象保留服务端字段，常用客户结构提供 `Customer`、`CustomerInput`、`ListResponse` 类型。
+
+```python
+from rcs_openapi import LeadIntakeRule
+
+rule = LeadIntakeRule.rules(
+    LeadIntakeRule.rule("success"),
+    LeadIntakeRule.rule("pending", "or", [
+        LeadIntakeRule.builtin("followup", "includes", "再联系,考虑"),
+        LeadIntakeRule.extract("意向车型", "notEquals", "无"),
+    ]),
+)
+# client.set_campaign_lead_intake_rule(campaign_id, rule)
+# client.reset_campaign_lead_intake_rule(campaign_id)  # 恢复系统默认
+```
+
+`create_campaign` 创建草稿；`set_campaign_status(id, "active")` 可能开始业务执行。`test_dial` 会实际下发拨号，必须由调用方明确发起；SDK 的自动测试不会拨号。
+
+`create_lead_from_call` 收到带 `leadId` 与 `alreadyExisted=true` 的409响应时正常返回，方便幂等处理；其它409仍抛异常。删除计划/场景/线索成功返回 `None`。`fetch_recording(recording_url)` 返回音频 `bytes`，使用录音 URL 自带的签名，不附加 API Bearer token，不跟随重定向。`decrypt_call_record`、`decrypt_marketing_lead` 提供相应 PII 解密。
+
+## 错误与超时
+
+```python
+from rcs_openapi import RcsOpenApiError, RcsTransportError, RcsProtocolError
+
+try:
+    customer = client.get_customer(customer_id)
+except RcsOpenApiError as error:
+    # error.status: 401/403/404/409/422/429/500 等；error.code 为服务端错误码
+    if error.status == 404:
+        pass  # 不存在或不在当前账号可见范围
+    else:
+        raise
+except RcsTransportError:
+    raise  # 连接/TLS/超时；创建可能已经成功，先按手机号查询确认结果
+except RcsProtocolError:
+    raise  # 无效 JSON/响应结构或意外重定向
+```
+
+不自动重试创建、编辑、删除或拨号；网络异常不会把密钥、token 或签名 URL 写入 SDK 异常消息。服务端业务错误保留其原始 message，调用方应按自己的日志脱敏规则处理。
+
+## Webhook 验签
+
+```python
+from rcs_openapi import WebhookReceiver, WebhookError
+
+receiver = WebhookReceiver(
+    webhook_secret,  # 端点独立签名密钥，不能拿 AK/SK 或 PII 密钥代替
+    pii_aes_key=pii_aes_key,
+    tolerance_seconds=300,
+)
+try:
+    event = receiver.parse(raw_request_body_bytes, request_headers)
+except WebhookError as error:
+    # error.code: missing_header / invalid_header / bad_signature /
+    # stale_timestamp / invalid_body；应拒绝处理
+    raise
+
+# 持久化检查 event.id 是否已处理；重复事件直接返回2xx。
+# 时间窗口不能替代按事件ID去重。
+if event.is_lead_created():
+    lead = event.decrypted_lead()
+elif event.is_device_alarm():
+    alarm = event.alarm()
+```
+
+验签必须使用**原始请求体字节**，不要先 JSON 解析再序列化。支持请求头大小写差异、HMAC-SHA256 常量时间比较、默认 ±300 秒时间窗口；事件属性包括 `id`、`type`、`api_version`、`occurred_at`、`user_id`、`data` 和 `envelope`。四类事件的便捷方法为 `lead()`/`decrypted_lead()`、`device()`/`offline()`/`alarm()`/`sim_registered()`，未知事件仍可读取原始 data。
+
+接收方负责持久化去重和业务任务投递，应快速返回2xx。SDK 不启动服务器，不强制绑定 Web 框架。[FastAPI 适配示例](examples/webhook_fastapi.py) 演示原始请求体验签，FastAPI 由调用方自行安装。
+
+## 开发与验证
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest -q
+ruff check src tests scripts examples
+ruff format --check src tests scripts examples
+mypy src
+python -m build
+python -m twine check dist/*
+```
+
+[验收记录](docs/validation.md) 区分协议单测、跨语言字节向量、真实 HTTP/PostgreSQL 和 wheel 安装结果。隔离验收脚本只接受 `127.0.0.1/localhost/::1:3033`，通过标准输入传入本轮凭据，禁止把生产凭据写进测试文件。SDK 本身仍可正常连接上述生产 HTTPS 域名。
+
+本软件为专有软件，使用与分发需获得授权。
+
+## 场景日汇总
+
+需已部署 `GET /stats/scenario-summary` 的服务端；测试基址为 `https://rcs-api.mimixiche.cn`，SDK 更新不代表生产接口已发布。
+
+```python
+totals = client.get_scenario_summary(
+    '2026-10-01', '2026-10-31', scenario_alias='insurance',
+)
+```
+
+必填日期包含首尾，相同日期统计一天；可选 `scenario_id` / `scenario_alias` 同时提供时取交集。返回 outboundCount、connectedCount、totalDurationSeconds（秒）、successCount、leadCount、outboundCustomerCount 六项累加值。仅查询已落库日统计，无匹配返回六项零，不补算当天/缺失日，客户数不跨日期/场景再次去重。服务端错误沿用 RcsOpenApiError，例如422不会转换成零。
+
+
+## 接口外呼任务（0.2.0 私有分发）
+
+```python
+request = {"campaignId": "cmp_xxx", "scenarioId": "scn_xxx", "phone": "13800138000", "externalRef": "order-001", "customer": {"name": "张三"}}
+task = client.create_outbound_call(request)
+current = client.get_outbound_call_task(task["taskId"])
+page = client.list_outbound_calls({"externalRef": request["externalRef"], "status": "queued"})
+```
+
+沿用后台预建并发布的接口计划，202是可靠受理，不表示已拨号。externalRef必传、用户内唯一；相同归一化请求重放200、内容变化409 external_ref_conflict，只有成功接单占号。SDK不自动重试写入、不生成或替换业务单号、不自动重拨。超时结果未知时由调用方沿用原单号和原请求重试，task_in_flight应查询已存在taskId，不能换号绕过。
+
+RcsOpenApiError保留code/message/status，并新增request_id、details；旧三参构造兼容。完整39项业务码由服务接入文档定义，典型包括external_ref_conflict、task_in_flight、missing_required_field、feature_disabled、no_available_window和payload_too_large。服务端可能带字段校验和已有taskId详情，调用方可按编码分支处理。
+
+WebhookEvent新增is_outbound_call_finished()/outbound_call_task()，沿用WebhookReceiver的真实原始体验签。事件ID是outbound_call.finished:<taskId>，接收方负责持久化去重；任务快照保持密文PII及当前权限，不触发自动解密或重拨。0.2.0只提供私有wheel/sdist，不发布公共PyPI；包发布不代表目标API已部署。
+
+### 合作方 API 登录（0.3.0）
+
+平台管理员先开通 API 登录，登记 HTTPS 回调及出口 IP 白名单。合作方后端通过
+`RcsOpenApiClient(base_url, partner_id=..., partner_client_id=..., partner_client_secret=...)` 配置凭证。
+调用 `send_partner_login_sms(phone)` 获取挑战，再以 `submit_partner_login(input, idempotency_key)`
+提交短信字段或 `method=password` 的密码字段。回调处理器使用
+`WebhookReceiver(signing_key).parse_partner_login(raw_body, headers)`，核对合作方和请求 ID，
+按事件 ID 去重。成功时将兑换码传给 `exchange_partner_login_code(code)`，按用户保存返回的访问令牌。
+同一提交重试复用幂等键，兑换不自动重试。密码方式需单独启用。
+
+### 主体管理与营销结果日统计
+
+使用 create_agent(input) 创建主体，必填 aliasName、storeAddress、entityType 和 name，可选 openTime、closeTime、storePhone。delete_agent(id) 归档主体，未结束计划仍引用时抛出 409 conflict。get_outbound_daily_stats(date) 的 marketingOutcomeCounts 返回 success、failure、no_effective_communication。
+
+### 当前用户资料
+
+使用已认证的客户端调用 `get_current_user()`，返回当前账号资料及适用的合作方绑定。

rcs_openapi_client-0.5.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+rcs_openapi/__init__.py,sha256=bhyQ5tkz3oROiHdY9d6yBch56qVQvG4S8J0cQDdc6Kg,861
+rcs_openapi/client.py,sha256=JnjYQULD5gaP7RnVgIG5mxz0YkEEm8LzXU-0VEcgSuA,19452
+rcs_openapi/errors.py,sha256=SE6_LO_oxFMV0ZuHrQO4_nSC8IOncIDWg5p-O9YYYVk,1115
+rcs_openapi/pii.py,sha256=KDAoOKPG6tOtQlxqwHcO-3Xmi95RDqzesT5pMJtPXrA,2225
+rcs_openapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rcs_openapi/rules.py,sha256=rJg3xNhQ_UCpB3nvcTXo3shF_KluUiChsjE_Ld4NAjs,4092
+rcs_openapi/types.py,sha256=wSF_pfoqC4nETthvMZuyNbxdOqhSUZ4EmvF82w__rDw,2025
+rcs_openapi/webhook.py,sha256=WTuT2vjLJipJaO3sxWCoq0z48e13q6ngBxJR8GaZai8,9556
+rcs_openapi_client-0.5.0.dist-info/licenses/LICENSE,sha256=bYc_KGnynGR-xE1LXkV1StYnRE6NJgnu5d2Sz_e9ggM,149
+rcs_openapi_client-0.5.0.dist-info/METADATA,sha256=ESbzPnFFdDG9L4egBEUzlUzBC5XheyUvjACZSzuVEfc,12503
+rcs_openapi_client-0.5.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+rcs_openapi_client-0.5.0.dist-info/top_level.txt,sha256=34JLKfruFbjViNms9F7P2P3RyT21Gxr5FPju9pohj1c,12
+rcs_openapi_client-0.5.0.dist-info/RECORD,,

rcs_openapi_client-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rcs_openapi_client-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+Copyright (c) 2026 Akimimi. All rights reserved.
+
+This software is proprietary. Use and redistribution require permission from the copyright holder.

rcs_openapi_client-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rcs_openapi