1#!/usr/bin/env python3
2"""
3CoinGecko API Utilities
4 
5This module provides utility functions for CoinGecko API tools including:
6- Natural language time parsing
7- Automatic data splitting for large time ranges  
8- Input validation and normalization
9- Cryptocurrency search functionality (search by name/symbol with market cap ranking)
10"""
11 
12import re
13from datetime import datetime, timedelta
14from typing import Union, List, Tuple, Optional, Dict
15import os
16from dotenv import load_dotenv
17 
18# Load environment variables
19load_dotenv()
20 
21import requests
22from core.http_client import proxied_get
23 
24 
25def normalize_timestamp_to_seconds(timestamp: Union[int, float]) -> int:
26    """
27    Automatically detect and convert timestamp format (seconds or milliseconds) to seconds.
28    
29    Args:
30        timestamp: Unix timestamp in seconds or milliseconds
31        
32    Returns:
33        int: Unix timestamp in seconds
34        
35    Example:
36        >>> normalize_timestamp_to_seconds(1672531200)     # seconds
37        1672531200
38        >>> normalize_timestamp_to_seconds(1672531200000)  # milliseconds
39        1672531200
40    """
41    timestamp = int(timestamp)
42    
43    # Timestamps after year 2001 and before year 2286 in milliseconds format
44    # Milliseconds: 13 digits, starts around 1000000000000 (2001)
45    # Seconds: 10 digits, starts around 1000000000 (2001)
46    if timestamp > 1000000000000:  # Likely milliseconds (13+ digits)
47        return timestamp // 1000
48    else:  # Likely seconds (10 digits or less)
49        return timestamp
50 
51 
52def normalize_timestamp_to_milliseconds(timestamp: Union[int, float]) -> int:
53    """
54    Automatically detect and convert timestamp format (seconds or milliseconds) to milliseconds.
55    
56    Args:
57        timestamp: Unix timestamp in seconds or milliseconds
58        
59    Returns:
60        int: Unix timestamp in milliseconds
61        
62    Example:
63        >>> normalize_timestamp_to_milliseconds(1672531200)     # seconds
64        1672531200000
65        >>> normalize_timestamp_to_milliseconds(1672531200000)  # milliseconds
66        1672531200000
67    """
68    timestamp = int(timestamp)
69    
70    if timestamp > 1000000000000:  # Already milliseconds
71        return timestamp
72    else:  # Convert from seconds to milliseconds
73        return timestamp * 1000
74 
75 
76def parse_flexible_time(time_input: Union[str, int, float]) -> int:
77    """
78    Parse flexible time input to Unix timestamp with automatic seconds/milliseconds conversion.
79    
80    Args:
81        time_input: Can be:
82            - Unix timestamp (int/float) - automatically detects seconds vs milliseconds
83            - ISO date string (YYYY-MM-DD)
84            - Natural language (e.g., "2 weeks ago", "yesterday", "last month")
85            - Datetime string (YYYY-MM-DD HH:MM:SS)
86    
87    Returns:
88        int: Unix timestamp in seconds
89    
90    Example:
91        >>> parse_flexible_time("2023-01-01")
92        1672531200
93        >>> parse_flexible_time("2 weeks ago")
94        # Returns timestamp for 2 weeks ago
95        >>> parse_flexible_time(1672531200)
96        1672531200
97        >>> parse_flexible_time(1672531200000)  # milliseconds auto-converted
98        1672531200
99    """
100    if isinstance(time_input, (int, float)):
101        # Auto-convert milliseconds to seconds if needed
102        return normalize_timestamp_to_seconds(time_input)
103    
104    # Clean string input and try to parse as timestamp first
105    time_str = str(time_input).strip().lower()
106    # Remove common shell artifacts like quotes
107    time_str = time_str.strip("'\"")
108    
109    # Try to parse as numeric timestamp first
110    if time_str.isdigit():
111        return normalize_timestamp_to_seconds(int(time_str))
112    
113    # Try ISO date formats
114    iso_patterns = [
115        r'^\d{4}-\d{2}-\d{2}$',  # YYYY-MM-DD
116        r'^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$',  # YYYY-MM-DD HH:MM:SS
117        r'^\d{4}/\d{2}/\d{2}$',  # YYYY/MM/DD
118        r'^\d{2}/\d{2}/\d{4}$',  # MM/DD/YYYY
119        r'^\d{2}-\d{2}-\d{4}$'   # DD-MM-YYYY (for historical data format)
120    ]
121    
122    for pattern in iso_patterns:
123        if re.match(pattern, time_str):
124            return _parse_date_string(time_str)
125    
126    # Parse natural language
127    return _parse_natural_language(time_str)
128 
129 
130def _parse_date_string(date_str: str) -> int:
131    """Parse various date string formats to Unix timestamp."""
132    formats = [
133        '%Y-%m-%d',
134        '%Y-%m-%d %H:%M:%S',
135        '%Y/%m/%d',
136        '%m/%d/%Y',
137        '%d-%m-%Y'
138    ]
139    
140    for fmt in formats:
141        try:
142            dt = datetime.strptime(date_str, fmt)
143            return int(dt.timestamp())
144        except ValueError:
145            continue
146    
147    raise ValueError(f"Unable to parse date string: {date_str}")
148 
149 
150def _parse_natural_language(text: str) -> int:
151    """Parse natural language time expressions to Unix timestamp."""
152    now = datetime.now()
153    
154    # Handle "today", "yesterday", etc.
155    if text in ['today', 'now']:
156        return int(now.timestamp())
157    elif text == 'yesterday':
158        return int((now - timedelta(days=1)).timestamp())
159    elif text == 'tomorrow':
160        return int((now + timedelta(days=1)).timestamp())
161    
162    # Handle relative time expressions
163    relative_patterns = [
164        (r'(\d+)\s*(second|sec)s?\s*ago', 'seconds'),
165        (r'(\d+)\s*(minute|min)s?\s*ago', 'minutes'),
166        (r'(\d+)\s*(hour|hr)s?\s*ago', 'hours'),
167        (r'(\d+)\s*(day)s?\s*ago', 'days'),
168        (r'(\d+)\s*(week)s?\s*ago', 'weeks'),
169        (r'(\d+)\s*(month)s?\s*ago', 'months'),
170        (r'(\d+)\s*(year)s?\s*ago', 'years'),
171        (r'last\s*(week)', 'weeks'),
172        (r'last\s*(month)', 'months'),
173        (r'last\s*(year)', 'years')
174    ]
175    
176    for pattern, unit in relative_patterns:
177        match = re.search(pattern, text)
178        if match:
179            if match.group(1).isdigit():
180                amount = int(match.group(1))
181            else:
182                amount = 1  # for "last week", etc.
183            
184            if unit == 'seconds':
185                delta = timedelta(seconds=amount)
186            elif unit == 'minutes':
187                delta = timedelta(minutes=amount)
188            elif unit == 'hours':
189                delta = timedelta(hours=amount)
190            elif unit == 'days':
191                delta = timedelta(days=amount)
192            elif unit == 'weeks':
193                delta = timedelta(weeks=amount)
194            elif unit == 'months':
195                # Approximate months as 30 days
196                delta = timedelta(days=amount * 30)
197            elif unit == 'years':
198                # Approximate years as 365 days
199                delta = timedelta(days=amount * 365)
200            else:
201                continue
202            
203            return int((now - delta).timestamp())
204    
205    raise ValueError(f"Unable to parse natural language time: {text}")
206 
207 
208def split_time_range(from_timestamp: int, to_timestamp: int, max_days: int = 180) -> List[Tuple[int, int]]:
209    """
210    Split a time range into chunks that don't exceed the maximum days limit.
211    
212    Args:
213        from_timestamp: Start timestamp
214        to_timestamp: End timestamp
215        max_days: Maximum days per chunk (default 180 for CoinGecko)
216    
217    Returns:
218        List of (start, end) timestamp tuples
219    
220    Example:
221        >>> splits = split_time_range(1640995200, 1672531200, 180)  # 1 year range
222        >>> len(splits)
223        3  # Split into 3 chunks
224    """
225    if from_timestamp >= to_timestamp:
226        raise ValueError("from_timestamp must be less than to_timestamp")
227    
228    total_seconds = to_timestamp - from_timestamp
229    max_seconds = max_days * 24 * 60 * 60  # Convert days to seconds
230    
231    if total_seconds <= max_seconds:
232        return [(from_timestamp, to_timestamp)]
233    
234    chunks = []
235    current_start = from_timestamp
236    
237    while current_start < to_timestamp:
238        current_end = min(current_start + max_seconds, to_timestamp)
239        chunks.append((current_start, current_end))
240        current_start = current_end
241    
242    return chunks
243 
244 
245def validate_coin_input(coin_input: str) -> str:
246    """
247    Validate and normalize coin input (ID or symbol).
248    
249    Args:
250        coin_input: Coin ID or symbol
251    
252    Returns:
253        str: Normalized coin input
254    
255    Raises:
256        ValueError: If input is invalid
257    """
258    if not coin_input or not isinstance(coin_input, str):
259        raise ValueError("Coin input must be a non-empty string")
260    
261    return coin_input.strip().lower()
262 
263 
264def format_dd_mm_yyyy_date(timestamp: int) -> str:
265    """
266    Convert Unix timestamp to dd-mm-yyyy format for CoinGecko historical API.
267    
268    Args:
269        timestamp: Unix timestamp
270    
271    Returns:
272        str: Date in dd-mm-yyyy format
273    """
274    dt = datetime.utcfromtimestamp(timestamp)
275    return dt.strftime('%d-%m-%Y')
276 
277 
278def get_days_difference(from_timestamp: int, to_timestamp: int) -> int:
279    """
280    Calculate the number of days between two timestamps.
281    
282    Args:
283        from_timestamp: Start timestamp
284        to_timestamp: End timestamp
285    
286    Returns:
287        int: Number of days
288    """
289    return int((to_timestamp - from_timestamp) / (24 * 60 * 60))
290 
291 
292def merge_ohlc_data(data_chunks: List[List]) -> List:
293    """
294    Merge multiple OHLC data chunks into a single list.
295    
296    Args:
297        data_chunks: List of OHLC data chunks
298    
299    Returns:
300        List: Merged OHLC data sorted by timestamp
301    """
302    merged = []
303    for chunk in data_chunks:
304        merged.extend(chunk)
305    
306    # Sort by timestamp (first element in each OHLC array)
307    merged.sort(key=lambda x: x[0])
308    
309    # Remove duplicates (same timestamp)
310    seen_timestamps = set()
311    unique_data = []
312    for item in merged:
313        timestamp = item[0]
314        if timestamp not in seen_timestamps:
315            seen_timestamps.add(timestamp)
316            unique_data.append(item)
317    
318    return unique_data
319 
320 
321def merge_market_chart_data(data_chunks: List[dict]) -> dict:
322    """
323    Merge multiple market chart data chunks into a single dictionary.
324    
325    Args:
326        data_chunks: List of market chart data dictionaries
327    
328    Returns:
329        dict: Merged market chart data with sorted timestamps
330    """
331    merged = {
332        'prices': [],
333        'market_caps': [],
334        'total_volumes': []
335    }
336    
337    for chunk in data_chunks:
338        if 'prices' in chunk:
339            merged['prices'].extend(chunk['prices'])
340        if 'market_caps' in chunk:
341            merged['market_caps'].extend(chunk['market_caps'])
342        if 'total_volumes' in chunk:
343            merged['total_volumes'].extend(chunk['total_volumes'])
344    
345    # Sort all arrays by timestamp
346    for key in merged:
347        merged[key].sort(key=lambda x: x[0])
348        
349        # Remove duplicates
350        seen_timestamps = set()
351        unique_data = []
352        for item in merged[key]:
353            timestamp = item[0]
354            if timestamp not in seen_timestamps:
355                seen_timestamps.add(timestamp)
356                unique_data.append(item)
357        merged[key] = unique_data
358    
359    return merged
360 
361 
362def search_coin_by_name(query: str) -> Optional[Dict[str, str]]:
363    """
364    Search for a cryptocurrency by name or symbol with intelligent input detection.
365    
366    - All uppercase input (e.g., "BTC") is treated as symbol search
367    - Input with ≤3 letters (e.g., "btc", "eth", "sol") is treated as symbol search
368    - Other mixed/lowercase input (e.g., "bitcoin", "Bitcoin") is treated as name search
369    - Symbol search: prioritizes exact symbol match, then market cap ranking
370    - Name search: prioritizes exact name match, then market cap ranking
371    
372    Special cases handled:
373    - ORDER/order/Order -> Orderly Network (orderly-network)
374    - orderly-network -> Returns directly as valid CoinGecko ID
375    
376    Args:
377        query (str): Search query - uppercase or ≤3 letters for symbol, otherwise name search
378        
379    Returns:
380        Optional[Dict[str, str]]: Dictionary with symbol, name, and id of the best match, or None if not found
381        
382    Example:
383        >>> search_coin_by_name("BTC")     # Symbol search (uppercase)
384        {'symbol': 'BTC', 'name': 'Bitcoin', 'id': 'bitcoin'}
385        >>> search_coin_by_name("btc")     # Symbol search (≤3 letters)
386        {'symbol': 'BTC', 'name': 'Bitcoin', 'id': 'bitcoin'}
387        >>> search_coin_by_name("bitcoin") # Name search (>3 letters, mixed case)
388        {'symbol': 'BTC', 'name': 'Bitcoin', 'id': 'bitcoin'}
389        >>> search_coin_by_name("order")   # Special case for Orderly Network
390        {'symbol': 'ORDER', 'name': 'Orderly Network', 'id': 'orderly-network'}
391        
392    Raises:
393        ValueError: If API key is missing or query is invalid
394        requests.RequestException: If API request fails
395    """
396    if not query or not isinstance(query, str):
397        raise ValueError("Query must be a non-empty string")
398    
399    # Special case mappings for ambiguous tokens and direct CoinGecko IDs
400    # When users say "ORDER", they almost always mean Orderly Network
401    # When users say "WOO", they mean WOO Network (id: woo-network, not woo)
402    special_mappings = {
403        'order': {'symbol': 'ORDER', 'name': 'Orderly Network', 'id': 'orderly-network'},
404        'ORDER': {'symbol': 'ORDER', 'name': 'Orderly Network', 'id': 'orderly-network'},
405        'Order': {'symbol': 'ORDER', 'name': 'Orderly Network', 'id': 'orderly-network'},
406        'orderly-network': {'symbol': 'ORDER', 'name': 'Orderly Network', 'id': 'orderly-network'},  # Handle direct ID
407        'woo': {'symbol': 'WOO', 'name': 'WOO', 'id': 'woo-network'},
408        'WOO': {'symbol': 'WOO', 'name': 'WOO', 'id': 'woo-network'},
409        'Woo': {'symbol': 'WOO', 'name': 'WOO', 'id': 'woo-network'},
410        'woo-network': {'symbol': 'WOO', 'name': 'WOO', 'id': 'woo-network'},  # Handle direct ID
411    }
412    
413    # Check for special cases first
414    query_stripped = query.strip()
415    if query_stripped in special_mappings:
416        return special_mappings[query_stripped]
417    
418    # Get API key
419    api_key = os.getenv("COINGECKO_API_KEY")
420    if not api_key:
421        raise ValueError(
422            "COINGECKO_API_KEY environment variable is required. "
423            "Get your API key from https://coingecko.com/en/api"
424        )
425    
426    # Prepare API request
427    url = "https://pro-api.coingecko.com/api/v3/search"
428    headers = {
429        "x-cg-pro-api-key": api_key,
430        "accept": "application/json"
431    }
432    params = {
433        "query": query.strip()
434    }
435    
436    try:
437        # Make single API request (no retry logic)
438        response = proxied_get(url, headers=headers, params=params, timeout=15)
439        response.raise_for_status()
440        
441        data = response.json()
442        
443        # Extract coins from search results
444        coins = data.get("coins", [])
445        
446        if not coins:
447            return None
448        
449        # Determine if input is symbol or name based on case and length
450        query_stripped = query.strip()
451        is_symbol_search = query_stripped.isupper() or len(query_stripped) <= 3
452        
453        if is_symbol_search:
454            # Symbol search: check for exact symbol OR exact name match in order of relevance
455            # This ensures "SOLANA" matches the real Solana (name match at index 0)
456            # rather than a meme coin with symbol "SOLANA" at index 18
457            for coin in coins:
458                coin_symbol = coin.get("symbol", "")
459                coin_name = coin.get("name", "")
460                if coin_symbol.upper() == query_stripped.upper() or coin_name.upper() == query_stripped.upper():
461                    return {
462                        "symbol": coin.get("symbol", "").upper(),
463                        "name": coin.get("name", ""),
464                        "id": coin.get("id", "")
465                    }
466 
467            # No exact symbol or name match, return highest market cap
468            best_coin = coins[0]
469            return {
470                "symbol": best_coin.get("symbol", "").upper(),
471                "name": best_coin.get("name", ""),
472                "id": best_coin.get("id", "")
473            }
474        else:
475            # Name search: prioritize exact name match, then market cap
476            for coin in coins:
477                coin_name = coin.get("name", "")
478                if coin_name.lower() == query_stripped.lower():
479                    return {
480                        "symbol": coin.get("symbol", "").upper(),
481                        "name": coin.get("name", ""),
482                        "id": coin.get("id", "")
483                    }
484            
485            # No exact name match, return highest market cap
486            best_coin = coins[0]
487            return {
488                "symbol": best_coin.get("symbol", "").upper(),
489                "name": best_coin.get("name", ""),
490                "id": best_coin.get("id", "")
491            }
492                
493    except requests.exceptions.Timeout:
494        raise requests.RequestException("Request timeout - CoinGecko API may be slow")
495    except requests.exceptions.ConnectionError:
496        raise requests.RequestException("Connection error - check internet connection")
497    except requests.exceptions.RequestException as e:
498        raise requests.RequestException(f"API request failed: {e}")
499    
500    return None
501 
502 
503