1"""
2TwelveData skill exports — script-mode skill.
3 
4Usage from a bash block:
5    python3 - <<'EOF'
6    import sys
7    sys.path.insert(0, "/data/workspace/skills/twelvedata")
8    from exports import twelvedata_price, twelvedata_time_series
9    print(twelvedata_price(symbol="AAPL"))
10    EOF
11 
12Imports from sidecar.proxy_client (NOT core.http_client) so this skill
13stays runnable without the agent platform's core/* modules on PYTHONPATH.
14"""
15import os
16 
17# Make sidecar/ importable when the script is invoked directly via
18# `python3 -c` from the agent's bash tool. /app is already on PYTHONPATH
19# inside the container (set by entrypoint.sh), so `from sidecar...` works
20# in production. The fallback covers local-dev runs from outside /app.
21try:
22    from sidecar.proxy_client import proxied_get
23except ImportError:
24    # Local dev / running outside the deployed image: fall back to
25    # core.http_client which is identical. Skill still works either way.
26    from core.http_client import proxied_get
27 
28API_KEY = os.environ.get("TWELVEDATA_API_KEY", "")
29BASE = "https://api.twelvedata.com"
30 
31 
32def _explain_error(code, body):
33    """Map a TwelveData error code to a short, actionable message.
34 
35    Never echoes the raw JSON body back to the agent (issue #243)."""
36    code = str(code)
37    msg = ""
38    if isinstance(body, dict):
39        msg = str(body.get("message", "")).strip()
40    if code == "404":
41        return (
42            "Symbol not found in TwelveData. Check the spelling, or use "
43            "twelvedata_search to find the correct ticker."
44        )
45    if code == "401":
46        return "TwelveData API key is invalid or missing (TWELVEDATA_API_KEY)."
47    if code == "429":
48        return "TwelveData rate limit hit. Wait before retrying."
49    # Generic: include the upstream message text only (not the full JSON).
50    return f"TwelveData API error {code}" + (f": {msg}" if msg else "")
51 
52 
53def _get(endpoint, params=None):
54    """Make a GET request to TwelveData API.
55 
56    TwelveData signals invalid symbols in two ways:
57      - an HTTP 4xx status, or
58      - HTTP 200 with an error envelope {"code": 404, "status": "error",
59        "message": ...} in the body.
60    Both are normalised into a clean RuntimeError so the agent sees an
61    actionable message instead of a raw JSON dump (issue #243)."""
62    if params is None:
63        params = {}
64    params["apikey"] = API_KEY
65    r = proxied_get(f"{BASE}/{endpoint}", params=params)
66 
67    # Non-2xx: surface a short readable error, not the raw body.
68    if r.status_code >= 400:
69        try:
70            body = r.json()
71        except Exception:
72            body = {}
73        raise RuntimeError(_explain_error(body.get("code", r.status_code), body))
74 
75    data = r.json()
76    # TwelveData frequently returns HTTP 200 with an error envelope.
77    if isinstance(data, dict) and str(data.get("status")) == "error":
78        raise RuntimeError(_explain_error(data.get("code", r.status_code), data))
79    return data
80 
81 
82def twelvedata_time_series(symbol, interval="1day", outputsize=30, start_date=None, end_date=None, prepost=False):
83    """Get OHLCV time series data."""
84    params = {"symbol": symbol, "interval": interval, "outputsize": outputsize}
85    if start_date:
86        params["start_date"] = start_date
87    if end_date:
88        params["end_date"] = end_date
89    if prepost:
90        params["prepost"] = "true"
91    return _get("time_series", params)
92 
93 
94def twelvedata_price(symbol, prepost=False):
95    """Get current price for a symbol."""
96    params = {"symbol": symbol}
97    if prepost:
98        params["prepost"] = "true"
99    return _get("price", params)
100 
101 
102def twelvedata_eod(symbol, date=None, prepost=False):
103    """Get end-of-day price."""
104    params = {"symbol": symbol}
105    if date:
106        params["date"] = date
107    if prepost:
108        params["prepost"] = "true"
109    return _get("eod", params)
110 
111 
112def twelvedata_quote(symbol, prepost=False):
113    """Get detailed quote (price, volume, 52w high/low, change %)."""
114    params = {"symbol": symbol}
115    if prepost:
116        params["prepost"] = "true"
117    return _get("quote", params)
118 
119 
120def twelvedata_quote_batch(symbols, prepost=False):
121    """Get quotes for multiple symbols. symbols: comma-separated string."""
122    params = {"symbol": symbols}
123    if prepost:
124        params["prepost"] = "true"
125    return _get("quote", params)
126 
127 
128def twelvedata_price_batch(symbols, prepost=False):
129    """Get prices for multiple symbols. symbols: comma-separated string."""
130    params = {"symbol": symbols}
131    if prepost:
132        params["prepost"] = "true"
133    return _get("price", params)
134 
135 
136def twelvedata_search(query):
137    """Search for symbols by name or ticker."""
138    return _get("symbol_search", {"symbol": query})
139 
140 
141def twelvedata_stocks(exchange=None, country=None):
142    """Get list of available stocks, optionally filtered."""
143    params = {}
144    if exchange:
145        params["exchange"] = exchange
146    if country:
147        params["country"] = country
148    return _get("stocks", params)
149 
150 
151def twelvedata_forex_pairs():
152    """Get all available forex pairs."""
153    return _get("forex_pairs")
154 
155 
156def twelvedata_exchanges():
157    """Get list of supported exchanges."""
158    return _get("exchanges")
159