1"""
2Twelve Data API Client — Async HTTP client for stocks and forex market data.
3 
4Supports stocks and forex (FX) data via REST API.
5Configured for Pro subscription tier endpoints only.
6 
7Environment Variables:
8- TWELVEDATA_API_KEY: Twelve Data API key (required, get from twelvedata.com)
9 
10Supported Endpoints (Pro Tier):
11- Time series data (price, quote, EOD, historical OHLCV)
12- Reference data (search, stocks list, forex pairs, exchanges)
13- Batch requests (multiple symbols)
14 
15Not Included (Requires Grow/Pro+/Ultra/Enterprise):
16- Fundamental data (financials, statistics, earnings)
17- Executive data (key executives, compensation)
18 
19API Documentation: https://twelvedata.com/docs
20"""
21 
22import logging
23import os
24from typing import Any, Dict, Optional, List
25 
26import aiohttp
27 
28from core.http_client import get_aiohttp_proxy_kwargs
29from core.tool import ToolResult
30 
31logger = logging.getLogger(__name__)
32 
33# ── Singleton client ──────────────────────────────────────────────
34_client: Optional["TwelveDataClient"] = None
35 
36 
37def get_client() -> "TwelveDataClient":
38    """Return a shared TwelveDataClient singleton."""
39    global _client
40    if _client is None:
41        _client = TwelveDataClient()
42    return _client
43 
44 
45def handle_api_error(e: Exception) -> ToolResult:
46    """Unified error handler for all Twelve Data tool execute() methods."""
47    error_str = str(e)
48    if "401" in error_str:
49        return ToolResult(
50            success=False,
51            error="API key error. The TWELVEDATA_API_KEY may be invalid or missing.",
52        )
53    if "429" in error_str:
54        return ToolResult(
55            success=False,
56            error="Rate limit exceeded. Please wait before making more requests.",
57        )
58    return ToolResult(success=False, error=f"Twelve Data API error: {error_str}")
59 
60# API Configuration
61BASE_URL = "https://api.twelvedata.com"
62 
63# Supported intervals for time series
64INTERVALS = ["1min", "5min", "15min", "30min", "45min", "1h", "2h", "4h", "8h", "1day", "1week", "1month"]
65 
66 
67class TwelveDataClient:
68    """
69    Async Twelve Data client for stocks and forex.
70 
71    All methods call the Twelve Data REST API with API key authentication.
72    Supports both header and query parameter authentication methods.
73    """
74 
75    def __init__(self, api_key: Optional[str] = None):
76        self.api_key = api_key or os.environ.get("TWELVEDATA_API_KEY", "")
77        if not self.api_key:
78            logger.warning("TWELVEDATA_API_KEY not set — API calls will fail")
79 
80    # ── Internal helpers ─────────────────────────────────────────────────
81 
82    async def _get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Any:
83        """GET request to Twelve Data API with API key auth."""
84        url = f"{BASE_URL}/{endpoint}"
85 
86        # Add API key to params (can also use header: Authorization: apikey YOUR_KEY)
87        if params is None:
88            params = {}
89        params["apikey"] = self.api_key
90 
91        headers = {
92            "Accept": "application/json",
93        }
94 
95        proxy_kw = get_aiohttp_proxy_kwargs(url)
96        async with aiohttp.ClientSession() as session:
97            async with session.get(
98                url,
99                headers=headers,
100                params=params,
101                timeout=aiohttp.ClientTimeout(total=30),
102                **proxy_kw,
103            ) as resp:
104                if resp.status >= 400:
105                    body = await resp.text()
106                    raise Exception(f"Twelve Data API {resp.status}: {body}")
107                return await resp.json()
108 
109    # ── Time Series & Price Data ─────────────────────────────────────────
110 
111    async def get_time_series(
112        self,
113        symbol: str,
114        interval: str = "1day",
115        outputsize: int = 30,
116        start_date: Optional[str] = None,
117        end_date: Optional[str] = None,
118        prepost: bool = False,
119    ) -> dict:
120        """
121        Get historical OHLCV time series data.
122 
123        Args:
124            symbol: Stock symbol (AAPL, MSFT) or forex pair (EUR/USD, GBP/JPY)
125            interval: Time interval (1min, 5min, 15min, 30min, 1h, 4h, 1day, 1week, 1month)
126            outputsize: Number of data points to return (1-5000). Default 30.
127            start_date: Start date in YYYY-MM-DD format (optional)
128            end_date: End date in YYYY-MM-DD format (optional)
129 
130        Returns:
131            dict with meta and values (OHLCV data)
132        """
133        params = {
134            "symbol": symbol,
135            "interval": interval,
136            "outputsize": outputsize,
137        }
138 
139        if start_date:
140            params["start_date"] = start_date
141        if end_date:
142            params["end_date"] = end_date
143        if prepost:
144            params["prepost"] = "true"
145 
146        return await self._get("time_series", params)
147 
148    async def get_quote(self, symbol: str, prepost: bool = False) -> dict:
149        """
150        Get real-time quote for a stock or forex pair.
151 
152        Args:
153            symbol: Stock symbol (AAPL) or forex pair (EUR/USD)
154            prepost: Include pre/post-market data when available (US/Cboe Europe, Pro+)
155 
156        Returns:
157            dict with current price, open, high, low, volume, change, etc.
158        """
159        params = {"symbol": symbol}
160        if prepost:
161            params["prepost"] = "true"
162        return await self._get("quote", params)
163 
164    async def get_price(self, symbol: str, prepost: bool = False) -> dict:
165        """
166        Get latest trading price.
167 
168        Args:
169            symbol: Stock symbol or forex pair
170            prepost: Include pre/post-market data when available (US/Cboe Europe, Pro+)
171 
172        Returns:
173            dict with price value
174        """
175        params = {"symbol": symbol}
176        if prepost:
177            params["prepost"] = "true"
178        return await self._get("price", params)
179 
180    async def get_eod(self, symbol: str, date: Optional[str] = None, prepost: bool = False) -> dict:
181        """
182        Get end-of-day price.
183 
184        Args:
185            symbol: Stock symbol or forex pair
186            date: Specific date in YYYY-MM-DD format (optional, defaults to latest)
187            prepost: Include pre/post-market data when available (US/Cboe Europe, Pro+)
188 
189        Returns:
190            dict with EOD price data
191        """
192        params = {"symbol": symbol}
193        if date:
194            params["date"] = date
195        if prepost:
196            params["prepost"] = "true"
197        return await self._get("eod", params)
198 
199    # ── Reference Data ───────────────────────────────────────────────────
200 
201    async def search_symbol(self, query: str) -> dict:
202        """
203        Search for stocks or forex pairs by name or symbol.
204 
205        Args:
206            query: Search query (company name, stock symbol, or currency pair)
207 
208        Returns:
209            dict with search results array
210        """
211        params = {"symbol": query}
212        return await self._get("symbol_search", params)
213 
214    async def get_stocks(
215        self,
216        exchange: Optional[str] = None,
217        country: Optional[str] = None,
218    ) -> dict:
219        """
220        Get list of available stocks.
221 
222        Args:
223            exchange: Filter by exchange (NASDAQ, NYSE, etc.)
224            country: Filter by country code (US, GB, etc.)
225 
226        Returns:
227            dict with stocks array
228        """
229        params = {}
230        if exchange:
231            params["exchange"] = exchange
232        if country:
233            params["country"] = country
234        return await self._get("stocks", params)
235 
236    async def get_forex_pairs(self) -> dict:
237        """
238        Get list of available forex pairs.
239 
240        Returns:
241            dict with forex pairs array
242        """
243        return await self._get("forex_pairs")
244 
245    async def get_exchanges(self) -> dict:
246        """
247        Get list of supported exchanges.
248 
249        Returns:
250            dict with exchanges array
251        """
252        return await self._get("exchanges")
253 
254    # ── Batch Requests ───────────────────────────────────────────────────
255 
256    async def get_quote_batch(self, symbols: List[str], prepost: bool = False) -> dict:
257        """
258        Get quotes for multiple symbols in one request.
259 
260        Args:
261            symbols: List of stock symbols or forex pairs (max 120)
262            prepost: Include pre/post-market data when available (US/Cboe Europe, Pro+)
263 
264        Returns:
265            dict with quotes for each symbol
266        """
267        if len(symbols) > 120:
268            logger.warning(f"Maximum 120 symbols per batch request. Truncating from {len(symbols)} to 120.")
269            symbols = symbols[:120]
270 
271        params = {"symbol": ",".join(symbols)}
272        if prepost:
273            params["prepost"] = "true"
274        return await self._get("quote", params)
275 
276    async def get_price_batch(self, symbols: List[str], prepost: bool = False) -> dict:
277        """
278        Get prices for multiple symbols in one request.
279 
280        Args:
281            symbols: List of stock symbols or forex pairs (max 120)
282            prepost: Include pre/post-market data when available (US/Cboe Europe, Pro+)
283 
284        Returns:
285            dict with prices for each symbol
286        """
287        if len(symbols) > 120:
288            logger.warning(f"Maximum 120 symbols per batch request. Truncating from {len(symbols)} to 120.")
289            symbols = symbols[:120]
290 
291        params = {"symbol": ",".join(symbols)}
292        if prepost:
293            params["prepost"] = "true"
294        return await self._get("price", params)
295