1"""
2Shared Coinglass API helper — eliminates return-None error pattern.
3 
4Every tools/*.py file repeated the same boilerplate:
5  1. _get_api_key() → return None if missing
6  2. proxied_get(url, headers, timeout) → return None on any error
7  3. check response code → return None if not "0"
8 
9This module centralizes that into one `cg_request()` function that:
10  - Raises typed exceptions instead of returning None
11  - Provides actionable error messages for each failure mode
12  - Distinguishes API key errors, rate limits, server errors, parse errors
13"""
14 
15import os
16import json
17import requests
18 
19try:
20    from core.http_client import proxied_get
21except ImportError:
22    # Fallback for testing outside platform — use plain requests
23    def proxied_get(url, params=None, headers=None, timeout=30,
24                    **kwargs):
25        return requests.get(
26            url, params=params, headers=headers, timeout=timeout,
27            **kwargs
28        )
29 
30 
31# ── Coinglass-specific exceptions ───────────────────────────
32 
33class CoinglassError(Exception):
34    """Base exception for all Coinglass API errors."""
35 
36    def __init__(self, message, code="UNKNOWN", suggestion=""):
37        self.code = code
38        self.suggestion = suggestion
39        super().__init__(message)
40 
41 
42class CoinglassAPIKeyError(CoinglassError):
43    """API key missing or invalid."""
44    pass
45 
46 
47class CoinglassRateLimitError(CoinglassError):
48    """Rate limited by Coinglass."""
49    pass
50 
51 
52class CoinglassServerError(CoinglassError):
53    """Coinglass server returned 5xx."""
54    pass
55 
56 
57# ── API configuration ──────────────────────────────────────
58 
59BASE_URL_V2 = "https://open-api.coinglass.com/public/v2"
60BASE_URL_V4 = "https://open-api-v4.coinglass.com"
61 
62HEADER_KEY_V2 = "coinglassSecret"
63HEADER_KEY_V4 = "CG-API-KEY"
64 
65 
66def _get_api_key():
67    """Get API key from environment."""
68    return os.getenv("COINGLASS_API_KEY")
69 
70 
71def _suggestion_for_status(status):
72    """Map HTTP status to actionable suggestion."""
73    suggestions = {
74        401: "API key invalid or expired. Check COINGLASS_API_KEY.",
75        403: "Access denied. This endpoint may require a paid plan.",
76        404: "Endpoint not found. The API version may have changed.",
77        429: "Rate limited. Wait 60 seconds before retrying.",
78        500: "Coinglass server error. Retry in 1-2 minutes.",
79        502: "Coinglass gateway error. Retry in 1-2 minutes.",
80        503: "Coinglass service unavailable. Retry in 1-2 minutes.",
81    }
82    return suggestions.get(status, f"HTTP {status} error.")
83 
84 
85def cg_request(endpoint, params=None, version="v4", timeout=30):
86    """
87    Make a Coinglass API request with structured error handling.
88 
89    Args:
90        endpoint: API path (e.g. "api/futures/supported-coins"
91                  or "funding" for v2)
92        params: Query parameters dict
93        version: "v2" or "v4" (default "v4")
94        timeout: Request timeout in seconds
95 
96    Returns:
97        Parsed response data (the "data" field from Coinglass response).
98 
99    Raises:
100        CoinglassAPIKeyError: API key missing or rejected
101        CoinglassRateLimitError: 429 rate limit
102        CoinglassServerError: 5xx server error
103        CoinglassError: Any other API error
104    """
105    api_key = _get_api_key()
106    if not api_key:
107        raise CoinglassAPIKeyError(
108            "COINGLASS_API_KEY not set in environment",
109            code="NO_API_KEY",
110            suggestion="Set COINGLASS_API_KEY in your .env file."
111        )
112 
113    if version == "v2":
114        base_url = BASE_URL_V2
115        headers = {"accept": "application/json", HEADER_KEY_V2: api_key}
116    else:
117        base_url = BASE_URL_V4
118        headers = {"accept": "application/json", HEADER_KEY_V4: api_key}
119 
120    url = f"{base_url}/{endpoint}"
121 
122    try:
123        response = proxied_get(
124            url, params=params, headers=headers, timeout=timeout
125        )
126        response.raise_for_status()
127    except requests.exceptions.HTTPError as e:
128        status = getattr(e.response, "status_code", None)
129        suggestion = _suggestion_for_status(status)
130        if status == 401:
131            raise CoinglassAPIKeyError(
132                f"HTTP 401 from Coinglass: {e}", code="HTTP_401",
133                suggestion=suggestion
134            ) from e
135        if status == 429:
136            raise CoinglassRateLimitError(
137                f"Rate limited by Coinglass: {e}", code="HTTP_429",
138                suggestion=suggestion
139            ) from e
140        if status and status >= 500:
141            raise CoinglassServerError(
142                f"Coinglass server error: {e}", code=f"HTTP_{status}",
143                suggestion=suggestion
144            ) from e
145        raise CoinglassError(
146            f"HTTP {status} from Coinglass: {e}",
147            code=f"HTTP_{status}", suggestion=suggestion
148        ) from e
149    except requests.exceptions.ConnectionError as e:
150        raise CoinglassError(
151            f"Cannot connect to Coinglass: {e}",
152            code="CONNECTION_ERROR",
153            suggestion="Check network. Retry in 30 seconds."
154        ) from e
155    except requests.exceptions.Timeout as e:
156        raise CoinglassError(
157            f"Coinglass request timed out after {timeout}s",
158            code="TIMEOUT",
159            suggestion="Retry with a longer timeout or simpler query."
160        ) from e
161    except requests.exceptions.RequestException as e:
162        raise CoinglassError(
163            f"Request failed: {type(e).__name__}: {e}",
164            code="REQUEST_ERROR",
165            suggestion="Unexpected network error. Retry."
166        ) from e
167 
168    # Parse JSON
169    try:
170        data = response.json()
171    except (json.JSONDecodeError, ValueError) as e:
172        raise CoinglassError(
173            f"Invalid JSON from Coinglass: {e}",
174            code="PARSE_ERROR",
175            suggestion="API may be returning an error page. Try again later."
176        ) from e
177 
178    # Check Coinglass response code
179    if isinstance(data, dict):
180        code = data.get("code")
181        if code is not None and str(code) != "0":
182            msg = data.get("msg", "Unknown API error")
183            raise CoinglassError(
184                f"Coinglass API error [{code}]: {msg}",
185                code=f"API_{code}",
186                suggestion="Check parameters. Some endpoints "
187                           "require specific symbols or exchanges."
188            )
189        # Unwrap standard response envelope
190        if "data" in data:
191            return data["data"]
192 
193    return data
194