echoscan 0.1.0__tar.gz

echoscan-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: echoscan
+Version: 0.1.0
+Summary: EchoScan package for Python
+Author: EchoScan Team
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# `echoscan` (Python)
+
+中文 | [English](#english)
+
+## 中文
+
+### 可用调用方式
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+方法：
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History 查询：
+
+仅 Pro 客户端可用（需要 Pro API Key）。
+
+### 返回值与错误
+
+`get_report()` 顶层结构：
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` 顶层结构：
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+完整字段说明链接：[echoscan](https://echoscan.org)
+
+
+### 示例
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```
+
+---
+
+## English
+
+### Usage
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+Methods:
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History query:
+
+Pro-only (requires a Pro API key).
+
+### Response and errors
+
+`get_report()` top-level shape:
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` top-level shape:
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+Full field reference: [echoscan](https://echoscan.org)
+
+
+### Example
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```

echoscan-0.1.0/README.md

@@ -0,0 +1,119 @@
+# `echoscan` (Python)
+
+中文 | [English](#english)
+
+## 中文
+
+### 可用调用方式
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+方法：
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History 查询：
+
+仅 Pro 客户端可用（需要 Pro API Key）。
+
+### 返回值与错误
+
+`get_report()` 顶层结构：
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` 顶层结构：
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+完整字段说明链接：[echoscan](https://echoscan.org)
+
+
+### 示例
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```
+
+---
+
+## English
+
+### Usage
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+Methods:
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History query:
+
+Pro-only (requires a Pro API key).
+
+### Response and errors
+
+`get_report()` top-level shape:
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` top-level shape:
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+Full field reference: [echoscan](https://echoscan.org)
+
+
+### Example
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```

echoscan-0.1.0/echoscan/__init__.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+DEFAULT_BASE_URL = "https://api.echoscan.org"
+DEFAULT_TIMEOUT_MS = 5000
+DEFAULT_RETRIES = 2
+SDK_USER_AGENT = "echoscan-python/0.1.0"
+
+
+@dataclass
+class ApiError(Exception):
+    code: str
+    http_status: int
+    message: str
+    request_id: Optional[str]
+    retryable: bool
+
+    def __str__(self) -> str:
+        return f"{self.message} ({self.code})"
+
+
+class _BaseClient:
+    def __init__(self, api_key: Optional[str]):
+        base_url = (os.getenv("ECHOSCAN_SERVER_BASE_URL") or DEFAULT_BASE_URL).strip()
+        self._base_url = base_url.rstrip("/")
+        self._timeout_ms = _parse_positive_int("ECHOSCAN_SERVER_TIMEOUT_MS", DEFAULT_TIMEOUT_MS)
+        self._retries = _parse_non_negative_int("ECHOSCAN_SERVER_RETRIES", DEFAULT_RETRIES)
+        self._api_key = api_key
+
+    def _get_json(self, path: str) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        max_attempts = self._retries + 1
+        last_error: Optional[ApiError] = None
+
+        for attempt in range(1, max_attempts + 1):
+            request_id = _generate_request_id()
+            headers = {
+                "Accept": "application/json",
+                "User-Agent": SDK_USER_AGENT,
+                "X-Request-Id": request_id,
+            }
+            if self._api_key:
+                headers["X-API-Key"] = self._api_key
+
+            request = urllib.request.Request(url=url, method="GET", headers=headers)
+            try:
+                with urllib.request.urlopen(request, timeout=self._timeout_ms / 1000) as response:
+                    body = response.read()
+                    return _json_or_empty(body)
+            except urllib.error.HTTPError as e:
+                code = _map_status_to_code(e.code)
+                retryable = attempt < max_attempts and (e.code >= 500 or e.code == 429)
+                response_request_id = e.headers.get("X-Request-Id") if e.headers else None
+                mapped = ApiError(
+                    code=code,
+                    http_status=e.code,
+                    message=_default_message(code),
+                    request_id=response_request_id or request_id,
+                    retryable=retryable,
+                )
+                if retryable:
+                    last_error = mapped
+                    continue
+                raise mapped
+            except urllib.error.URLError as e:
+                timeout = "timed out" in str(e).lower()
+                code = "timeout" if timeout else "network_error"
+                status = 408 if timeout else 0
+                retryable = attempt < max_attempts
+                mapped = ApiError(
+                    code=code,
+                    http_status=status,
+                    message=_default_message(code),
+                    request_id=request_id,
+                    retryable=retryable,
+                )
+                if retryable:
+                    last_error = mapped
+                    continue
+                raise mapped
+
+        if last_error:
+            raise last_error
+        raise ApiError(
+            code="unknown_error",
+            http_status=0,
+            message="Unexpected error",
+            request_id=None,
+            retryable=False,
+        )
+
+
+class EchoScanLiteClient(_BaseClient):
+    def __init__(self):
+        super().__init__(api_key=None)
+
+    def get_report(self, imprint: str) -> Dict[str, Any]:
+        normalized = _assert_imprint(imprint)
+        return self._get_json(f"/report-lite/{urllib.parse.quote(normalized, safe='')}")
+
+
+class EchoScanProClient(_BaseClient):
+    def __init__(self, api_key: str):
+        normalized_key = _assert_api_key(api_key, "pro")
+        super().__init__(api_key=normalized_key)
+
+    def get_report(self, imprint: str) -> Dict[str, Any]:
+        normalized = _assert_imprint(imprint)
+        return self._get_json(f"/api/v1/fingerprint/report/{urllib.parse.quote(normalized, safe='')}")
+
+    def get_history(
+        self,
+        imprint: str,
+        *,
+        days: Optional[int] = None,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        recent: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        normalized = _assert_imprint(imprint)
+        query = _build_history_query(days=days, from_=from_, to=to, recent=recent)
+        path = f"/api/v1/fingerprint/imprint/{urllib.parse.quote(normalized, safe='')}/history{query}"
+        return self._get_json(path)
+
+
+class EchoScanDebugClient(_BaseClient):
+    def __init__(self, api_key: str):
+        normalized_key = _assert_api_key(api_key, "debug")
+        super().__init__(api_key=normalized_key)
+
+    def get_report(self, imprint: str) -> Dict[str, Any]:
+        normalized = _assert_imprint(imprint)
+        return self._get_json(
+            f"/api/v1/internal/fingerprint/report/{urllib.parse.quote(normalized, safe='')}"
+        )
+
+    def get_details(self, imprint: str) -> Dict[str, Any]:
+        normalized = _assert_imprint(imprint)
+        return self._get_json(
+            f"/api/v1/internal/fingerprint/details/{urllib.parse.quote(normalized, safe='')}"
+        )
+
+
+def _assert_imprint(imprint: str) -> str:
+    normalized = (imprint or "").strip()
+    if not normalized:
+        raise ApiError(
+            code="invalid_request",
+            http_status=400,
+            message="imprint must be a non-empty string",
+            request_id=None,
+            retryable=False,
+        )
+    return normalized
+
+
+def _assert_api_key(api_key: str, role: str) -> str:
+    normalized = (api_key or "").strip()
+    if not normalized:
+        raise ApiError(
+            code="invalid_request",
+            http_status=400,
+            message=f"apiKey is required for {role} client",
+            request_id=None,
+            retryable=False,
+        )
+    return normalized
+
+
+def _build_history_query(
+    *, days: Optional[int], from_: Optional[str], to: Optional[str], recent: Optional[int]
+) -> str:
+    has_days = days is not None
+    has_from = from_ is not None
+    has_to = to is not None
+
+    if has_days and (has_from or has_to):
+        raise ApiError(
+            code="invalid_request",
+            http_status=400,
+            message="history query: days and from/to are mutually exclusive",
+            request_id=None,
+            retryable=False,
+        )
+    if has_from != has_to:
+        raise ApiError(
+            code="invalid_request",
+            http_status=400,
+            message="history query: from and to must be provided together",
+            request_id=None,
+            retryable=False,
+        )
+
+    params = {}
+    if has_days:
+        if not isinstance(days, int) or days <= 0:
+            raise ApiError(
+                code="invalid_request",
+                http_status=400,
+                message="history query: days must be a positive number",
+                request_id=None,
+                retryable=False,
+            )
+        params["days"] = str(days)
+    if has_from and has_to:
+        if not _is_yyyy_mm_dd(str(from_)):
+            raise ApiError(
+                code="invalid_request",
+                http_status=400,
+                message="from must use YYYY-MM-DD format",
+                request_id=None,
+                retryable=False,
+            )
+        if not _is_yyyy_mm_dd(str(to)):
+            raise ApiError(
+                code="invalid_request",
+                http_status=400,
+                message="to must use YYYY-MM-DD format",
+                request_id=None,
+                retryable=False,
+            )
+        if str(from_) > str(to):
+            raise ApiError(
+                code="invalid_request",
+                http_status=400,
+                message="history query: from must be <= to",
+                request_id=None,
+                retryable=False,
+            )
+        params["from"] = str(from_)
+        params["to"] = str(to)
+    if recent is not None:
+        if not isinstance(recent, int) or recent <= 0:
+            raise ApiError(
+                code="invalid_request",
+                http_status=400,
+                message="history query: recent must be a positive number",
+                request_id=None,
+                retryable=False,
+            )
+        params["recent"] = str(recent)
+
+    if not params:
+        return ""
+    return "?" + urllib.parse.urlencode(params)
+
+
+def _is_yyyy_mm_dd(value: str) -> bool:
+    if len(value) != 10 or value[4] != "-" or value[7] != "-":
+        return False
+    y, m, d = value[:4], value[5:7], value[8:10]
+    return y.isdigit() and m.isdigit() and d.isdigit()
+
+
+def _parse_positive_int(name: str, fallback: int) -> int:
+    raw = (os.getenv(name) or "").strip()
+    if not raw:
+        return fallback
+    try:
+        value = int(raw)
+        return value if value > 0 else fallback
+    except ValueError:
+        return fallback
+
+
+def _parse_non_negative_int(name: str, fallback: int) -> int:
+    raw = (os.getenv(name) or "").strip()
+    if not raw:
+        return fallback
+    try:
+        value = int(raw)
+        return value if value >= 0 else fallback
+    except ValueError:
+        return fallback
+
+
+def _map_status_to_code(status: int) -> str:
+    if status == 400:
+        return "invalid_request"
+    if status == 401:
+        return "auth_failed"
+    if status == 403:
+        return "forbidden"
+    if status == 404:
+        return "not_found"
+    if status == 408:
+        return "timeout"
+    if status == 429:
+        return "quota_exceeded"
+    if status in (500, 502, 503, 504):
+        return "upstream_unavailable"
+    return "unknown_error"
+
+
+def _default_message(code: str) -> str:
+    return {
+        "invalid_request": "Invalid request",
+        "auth_failed": "Authentication failed",
+        "forbidden": "Forbidden",
+        "not_found": "Not found",
+        "quota_exceeded": "Quota exceeded",
+        "timeout": "Request timed out",
+        "upstream_unavailable": "Upstream service unavailable",
+        "network_error": "Network error",
+        "unknown_error": "Unexpected error",
+    }.get(code, "Unexpected error")
+
+
+def _generate_request_id() -> str:
+    return f"req_{time.time_ns()}_{random.randint(100000, 999999)}"
+
+
+def _json_or_empty(raw: bytes) -> Dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        decoded = json.loads(raw.decode("utf-8"))
+    except Exception:
+        return {}
+    return decoded if isinstance(decoded, dict) else {}

echoscan-0.1.0/echoscan.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: echoscan
+Version: 0.1.0
+Summary: EchoScan package for Python
+Author: EchoScan Team
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# `echoscan` (Python)
+
+中文 | [English](#english)
+
+## 中文
+
+### 可用调用方式
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+方法：
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History 查询：
+
+仅 Pro 客户端可用（需要 Pro API Key）。
+
+### 返回值与错误
+
+`get_report()` 顶层结构：
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` 顶层结构：
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+完整字段说明链接：[echoscan](https://echoscan.org)
+
+
+### 示例
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```
+
+---
+
+## English
+
+### Usage
+
+- `EchoScanLiteClient()`
+- `EchoScanProClient(api_key=...)`
+
+Methods:
+
+- Lite: `get_report(imprint)`
+- Pro: `get_report(imprint)`, `get_history(imprint, days=..., from_=..., to=..., recent=...)`
+
+History query:
+
+Pro-only (requires a Pro API key).
+
+### Response and errors
+
+`get_report()` top-level shape:
+
+```json
+{
+  "analysis": {},
+  "lyingCount": 0,
+  "projection": {}
+}
+```
+
+`get_history()` top-level shape:
+
+```json
+{
+  "imprint": "fp_session_...",
+  "range": {},
+  "recent": [],
+  "summary": {},
+  "timeline": []
+}
+```
+
+Full field reference: [echoscan](https://echoscan.org)
+
+
+### Example
+
+```python
+import os
+from echoscan import EchoScanProClient
+
+pro = EchoScanProClient(api_key=os.environ["ECHOSCAN_PRO_KEY"])
+report = pro.get_report("fp_session_123")
+history = pro.get_history("fp_session_123", from_="2026-03-01", to="2026-03-18", recent=20)
+
+print(report)
+print(history)
+```

echoscan-0.1.0/echoscan.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+echoscan/__init__.py
+echoscan.egg-info/PKG-INFO
+echoscan.egg-info/SOURCES.txt
+echoscan.egg-info/dependency_links.txt
+echoscan.egg-info/top_level.txt

echoscan-0.1.0/echoscan.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

echoscan-0.1.0/echoscan.egg-info/top_level.txt

@@ -0,0 +1 @@
+echoscan

echoscan-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "echoscan"
+version = "0.1.0"
+description = "EchoScan package for Python"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "EchoScan Team" }
+]
+license = { text = "MIT" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["echoscan*"]

echoscan-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+