refactor: streamline API architecture and improve type safety

- Consolidate API methods and simplify class structure
- Enhance type definitions and model consistency
- Update examples to reflect new API patterns
- Improve test coverage for core functionality

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: codebydivine

examples/endpoints/evm/balances.py

@@ -1,18 +1,16 @@
 #!/usr/bin/env python3
 """Token Balances Example - See your crypto portfolio instantly."""
 
+# Import shared helper functions
+import sys
+from pathlib import Path
+
 import anyio
 
 from thegraph_token_api import TokenAPI
 
-
-def format_amount(value):
-    """Format large numbers with K/M suffixes."""
-    if value >= 1_000_000:
-        return f"{value / 1_000_000:.1f}M"
-    if value >= 1_000:
-        return f"{value / 1_000:.1f}K"
-    return f"{value:.2f}"
+sys.path.append(str(Path(__file__).parent.parent.parent))
+from _helpers import format_amount
 
 
 async def main():

examples/endpoints/evm/prices.py

@@ -1,12 +1,18 @@
 #!/usr/bin/env python3
 """Price History Example - Track token prices over time."""
 
+# Import shared helper functions
+import sys
 from datetime import datetime
+from pathlib import Path
 
 import anyio
 
 from thegraph_token_api import Interval, TokenAPI
 
+sys.path.append(str(Path(__file__).parent.parent.parent))
+from _helpers import format_price_change
+
 
 def parse_datetime(datetime_str):
     """Parse ISO datetime string safely."""
@@ -16,14 +22,6 @@ def parse_datetime(datetime_str):
         return None
 
 
-def format_price_change(open_price, close_price):
-    """Calculate and format price change percentage."""
-    if not open_price or open_price == 0:
-        return "±0.0%"
-    change = ((close_price - open_price) / open_price) * 100
-    return f"{change:+.1f}%"
-
-
 async def main():
     print("📈 Price History")
     print("=" * 16)

examples/endpoints/evm/transfers.py

@@ -1,19 +1,16 @@
 #!/usr/bin/env python3
 """Token Transfers Example - Track token movements on-chain."""
 
-from datetime import datetime
+# Import shared helper functions
+import sys
+from pathlib import Path
 
 import anyio
 
 from thegraph_token_api import TokenAPI
 
-
-def format_time(timestamp):
-    """Format timestamp to readable time."""
-    try:
-        return datetime.fromtimestamp(timestamp).strftime("%H:%M")
-    except (ValueError, OSError, OverflowError):
-        return "??:??"
+sys.path.append(str(Path(__file__).parent.parent.parent))
+from _helpers import format_time
 
 
 async def main():

examples/endpoints/svm/swaps.py

@@ -1,26 +1,16 @@
 #!/usr/bin/env python3
 """Solana DEX Swaps Example - Track Solana trading activity."""
 
-from datetime import datetime
+# Import shared helper functions
+import sys
+from pathlib import Path
 
 import anyio
 
 from thegraph_token_api import SwapPrograms, TokenAPI
 
-
-def get_symbol(mint_obj):
-    """Get token symbol or shortened mint address."""
-    if hasattr(mint_obj, "symbol") and mint_obj.symbol:
-        return mint_obj.symbol
-    return str(mint_obj)[:6] + "..."
-
-
-def format_time(timestamp):
-    """Format timestamp to readable time."""
-    try:
-        return datetime.fromtimestamp(timestamp).strftime("%H:%M")
-    except (ValueError, OSError, OverflowError):
-        return "??:??"
+sys.path.append(str(Path(__file__).parent.parent.parent))
+from _helpers import format_time, get_symbol
 
 
 async def main():

src/thegraph_token_api/__init__.py

@@ -80,6 +80,7 @@ async def main():
     SolanaTransfer,
     SolanaTransfersResponse,
     Statistics,
+    StringEnum,
     Swap,
     SwapPrograms,
     SwapsResponse,
@@ -98,6 +99,7 @@ async def main():
 __all__ = [
     "TokenAPI",  # Main interface
     # Export all types
+    "StringEnum",
     "NetworkId",
     "SolanaNetworkId",
     "TokenStandard",

src/thegraph_token_api/base.py

@@ -5,6 +5,7 @@
 """
 
 import os
+from typing import Any
 
 # Import divine-typed-requests (should be installed as a package)
 from typed_requests import NetworkingManager  # type: ignore[attr-defined]
@@ -49,6 +50,23 @@ def _validate_pagination(self, limit: int, page: int) -> None:
         if page < 1:
             raise ValueError("page must be 1 or greater")
 
+    def _build_base_params(self, network: str, limit: int = 10, page: int = 1) -> dict[str, str | int]:
+        """Build base parameters common to most API calls."""
+        self._validate_pagination(limit, page)
+        return {
+            "network_id": network,
+            "limit": limit,
+            "page": page,
+        }
+
+    def _add_optional_params(self, params: dict, **kwargs: Any) -> dict:
+        """Add optional parameters to params dict, excluding None values."""
+        for key, value in kwargs.items():
+            if value is not None:
+                # Convert enum values to strings
+                params[key] = str(value) if hasattr(value, "value") else value
+        return params
+
     async def __aenter__(self):
         """Async context manager entry."""
         await self.manager.startup()

src/thegraph_token_api/evm.py

@@ -90,10 +90,8 @@ async def get_nft_ownerships(
         Returns:
             NFTOwnershipsResponse with validated data
         """
-        self._validate_pagination(limit, page)
-        params = {"network_id": self.network, "limit": limit, "page": page}
-        if token_standard:
-            params["token_standard"] = str(token_standard)
+        params = self._build_base_params(self.network, limit, page)
+        self._add_optional_params(params, token_standard=token_standard)
 
         response = await self.manager.get(
             f"{self.base_url}/nft/ownerships/evm/{address}",

src/thegraph_token_api/models.py

@@ -13,15 +13,7 @@
 
 @dataclass
 class BaseModel:
-    """Base model with dict-like access for backward compatibility."""
-
-    def __getitem__(self, key):
-        """Support dictionary-style access for backward compatibility."""
-        return getattr(self, key, None)
-
-    def get(self, key, default=None):
-        """Support .get() method for backward compatibility."""
-        return getattr(self, key, default)
+    """Base model class."""
 
 
 @dataclass
@@ -139,18 +131,6 @@ class Transfer(BaseModel):
     symbol: str | None = None
     decimals: float | None = None
 
-    def __getitem__(self, key):
-        """Support dictionary-style access with 'from' key mapping."""
-        if key == "from":
-            return self.from_address
-        return super().__getitem__(key)
-
-    def get(self, key, default=None):
-        """Support .get() method with 'from' key mapping."""
-        if key == "from":
-            return self.from_address
-        return super().get(key, default)
-
 
 @dataclass
 class SolanaTransfer(BaseModel):
@@ -223,22 +203,6 @@ class NFTActivity(BaseModel):
     transfer_type: str | None = None
     token_standard: str | None = None
 
-    def __getitem__(self, key):
-        """Support dictionary-style access with special key mappings."""
-        if key == "@type":
-            return self.activity_type
-        if key == "from":
-            return self.from_address
-        return super().__getitem__(key)
-
-    def get(self, key, default=None):
-        """Support .get() method with special key mappings."""
-        if key == "@type":
-            return self.activity_type
-        if key == "from":
-            return self.from_address
-        return super().get(key, default)
-
 
 @dataclass
 class Token(BaseModel):