feat: extend typed response models to all documented data endpoints (#141)

Follow-up to the candle/ticker pilot: add TypedDicts for announcement, token
updates, wallet status, forex, funding rate (history + latest), premium
(incl. ~75-field detail, total=False), telegram channels/messages, and naver
trend; annotate each method's pandas=False return with the matching model
(envelope / bare list / single object per the actual return shape).

Fields sourced from the live API docs. Typed str to match the API's
string-on-the-wire serialization, with two verified native exceptions:
premium booleans (t/sms/tms) and naver trend v (int). Hint-only; no runtime
cost or behavior change. All models exported from the top level.

Endpoints returning raw request_endpoint() dicts without published field
schemas (liquidation, open_interest, margin_borrow, index_price, cex.symbol)
are intentionally left untyped rather than guessed.

Author: martinkersner

datamaxi/__init__.py

@@ -25,6 +25,23 @@
     CandleResponse,
     TickerData,
     TickerResponse,
+    AnnouncementRow,
+    AnnouncementResponse,
+    TokenUpdateRow,
+    TokenUpdateResponse,
+    WalletStatusRow,
+    ForexRow,
+    FundingRateRow,
+    FundingHistoryResponse,
+    LatestFundingRate,
+    PremiumDetail,
+    PremiumRow,
+    PremiumResponse,
+    TelegramChannel,
+    TelegramChannelsResponse,
+    TelegramMessage,
+    TelegramMessagesResponse,
+    NaverTrendRow,
 )
 
 __all__ = [
@@ -52,4 +69,21 @@
     "CandleResponse",
     "TickerData",
     "TickerResponse",
+    "AnnouncementRow",
+    "AnnouncementResponse",
+    "TokenUpdateRow",
+    "TokenUpdateResponse",
+    "WalletStatusRow",
+    "ForexRow",
+    "FundingRateRow",
+    "FundingHistoryResponse",
+    "LatestFundingRate",
+    "PremiumDetail",
+    "PremiumRow",
+    "PremiumResponse",
+    "TelegramChannel",
+    "TelegramChannelsResponse",
+    "TelegramMessage",
+    "TelegramMessagesResponse",
+    "NaverTrendRow",
 ]

datamaxi/naver/__init__.py

@@ -1,6 +1,7 @@
 from typing import Any, List, Union
 import pandas as pd
 from datamaxi.api import Resource
+from datamaxi.resources.responses import NaverTrendRow
 from datamaxi.lib.utils import check_required_parameter
 from datamaxi.lib.constants import BASE_URL
 
@@ -31,7 +32,9 @@ def symbols(self) -> List[str]:
         """
         return self.request_endpoint("naver_trend_symbols")
 
-    def trend(self, symbol: str, pandas: bool = True) -> Union[List, pd.DataFrame]:
+    def trend(
+        self, symbol: str, pandas: bool = True
+    ) -> Union[pd.DataFrame, List[NaverTrendRow]]:
         """Get Naver trend for given token symbol
 
         `GET /api/v1/naver-trend`

datamaxi/resources/cex_announcement.py

@@ -1,5 +1,6 @@
-from typing import Any, Dict, Optional, Tuple, Callable
+from typing import Any, Optional, Tuple, Callable
 from datamaxi.api import Resource
+from datamaxi.resources.responses import AnnouncementResponse
 from datamaxi.lib.constants import ASC, DESC, SortOrder
 
 
@@ -23,7 +24,7 @@ def __call__(
         key: Optional[str] = None,
         exchange: Optional[str] = None,
         category: Optional[str] = None,
-    ) -> Tuple[Dict[str, Any], Callable]:
+    ) -> Tuple[AnnouncementResponse, Callable]:
         """Get exchange announcements
 
         `GET /api/v1/cex/announcements`

datamaxi/resources/cex_token.py

@@ -1,5 +1,6 @@
-from typing import Any, Dict, Optional, Tuple, Callable
+from typing import Any, Optional, Tuple, Callable
 from datamaxi.api import Resource
+from datamaxi.resources.responses import TokenUpdateResponse
 
 
 class CexToken(Resource):
@@ -19,7 +20,7 @@ def updates(
         page: int = 1,
         limit: int = 1000,
         type: Optional[str] = None,
-    ) -> Tuple[Dict[str, Any], Callable]:
+    ) -> Tuple[TokenUpdateResponse, Callable]:
         """Get token update data
 
         `GET /api/v1/cex/token/updates`

datamaxi/resources/cex_wallet_status.py

@@ -1,6 +1,7 @@
-from typing import Any, List, Dict, Union
+from typing import Any, List, Union
 import pandas as pd
 from datamaxi.api import Resource
+from datamaxi.resources.responses import WalletStatusRow
 from datamaxi.lib.utils import check_required_parameters
 from datamaxi.lib.utils import check_required_parameter
 
@@ -22,7 +23,7 @@ def __call__(
         exchange: str,
         asset: str,
         pandas: bool = True,
-    ) -> Union[Dict, pd.DataFrame]:
+    ) -> Union[pd.DataFrame, List[WalletStatusRow]]:
         """Fetch transfer status data
 
         `GET /api/v1/wallet-status`

datamaxi/resources/forex.py

@@ -1,6 +1,7 @@
-from typing import Any, List, Dict, Union
+from typing import Any, List, Union
 import pandas as pd
 from datamaxi.api import Resource
+from datamaxi.resources.responses import ForexRow
 from datamaxi.lib.utils import check_required_parameter
 
 
@@ -23,7 +24,7 @@ def __call__(
         self,
         symbol: str,
         pandas: bool = True,
-    ) -> Union[Dict, pd.DataFrame]:
+    ) -> Union[pd.DataFrame, ForexRow]:
         """Fetch forex data
 
         `GET /api/v1/forex`

datamaxi/resources/funding_rate.py

@@ -1,9 +1,10 @@
-from typing import Any, Callable, Tuple, List, Dict, Union
+from typing import Any, Callable, Tuple, List, Union
 import pandas as pd
 from datamaxi.api import Resource
 from datamaxi.lib.utils import check_required_parameter
 from datamaxi.lib.utils import check_required_parameters
 from datamaxi.resources.utils import convert_data_to_data_frame
+from datamaxi.resources.responses import FundingHistoryResponse, LatestFundingRate
 from datamaxi.lib.constants import ASC, DESC, SortOrder
 
 
@@ -29,7 +30,7 @@ def history(
         toDateTime: str = None,
         sort: SortOrder = DESC,
         pandas: bool = True,
-    ) -> Union[Tuple[Dict, Callable], Tuple[pd.DataFrame, Callable]]:
+    ) -> Union[Tuple[pd.DataFrame, Callable], Tuple[FundingHistoryResponse, Callable]]:
         """Fetch historical funding rate data
 
         `GET /api/v1/funding-rate/history`
@@ -105,7 +106,7 @@ def latest(
         exchange: str = None,
         symbol: str = None,
         pandas: bool = True,
-    ) -> Union[Dict, pd.DataFrame]:
+    ) -> Union[pd.DataFrame, LatestFundingRate]:
         """Fetch latest funding rate data
 
         `GET /api/v1/funding-rate/latest`

datamaxi/resources/premium.py

@@ -1,6 +1,7 @@
 from typing import Any, List, Union, Optional
 import pandas as pd
 from datamaxi.api import Resource
+from datamaxi.resources.responses import PremiumResponse
 from datamaxi.lib.constants import Market, SortOrder
 
 
@@ -43,7 +44,7 @@ def __call__(  # noqa: C901
         token_exclude: str = None,
         query: str = None,
         pandas: bool = True,
-    ) -> Union[List, pd.DataFrame]:
+    ) -> Union[pd.DataFrame, PremiumResponse]:
         """Fetch premium data
 
         `GET /api/v1/premium`