chipi-stack 2.0.0__py3-none-any.whl

chipi_sdk/client.py

@@ -0,0 +1,505 @@
+"""HTTP client for Chipi API interactions."""
+
+from typing import Any, Dict, Optional, TypeVar
+import httpx
+
+from .models.core import ChipiSDKConfig
+from .errors import ChipiAuthError, ChipiApiError, handle_api_error
+from .validators import is_valid_api_key, validate_error_response
+from .constants import API_VERSION, API_VERSION_DATE, STARKNET_NETWORKS
+
+T = TypeVar('T')
+
+
+class ChipiClient:
+    """HTTP client with sync and async support."""
+
+    def __init__(self, config: ChipiSDKConfig):
+        """
+        Initialize the Chipi HTTP client.
+
+        Args:
+            config: SDK configuration
+
+        Raises:
+            ChipiAuthError: If API key is invalid
+        """
+        if not is_valid_api_key(config.api_public_key):
+            raise ChipiAuthError("Invalid API key format")
+
+        self.api_public_key = config.api_public_key
+        self.custom_alpha_url = config.alpha_url
+        self.base_url = self._get_base_url()
+        self.node_url = config.node_url or STARKNET_NETWORKS["MAINNET"]
+        self.sdk_version = "2.0.0"
+
+        # Initialize HTTP clients
+        self._sync_client = httpx.Client(timeout=30.0)
+        self._async_client = httpx.AsyncClient(timeout=30.0)
+
+    def get_api_public_key(self) -> str:
+        """Get the API public key (for internal SDK use)."""
+        return self.api_public_key
+
+    def _get_base_url(self) -> str:
+        """Construct the base API URL."""
+        version = f"v{API_VERSION}"
+
+        if self.custom_alpha_url:
+            # Remove any existing version suffix and add the current one
+            clean_url = self.custom_alpha_url.rstrip('/')
+            # Remove existing version if present
+            if clean_url.endswith(f'/v{API_VERSION}'):
+                clean_url = clean_url[:-len(f'/v{API_VERSION}')]
+            return f"{clean_url}/{version}"
+
+        return f"https://api.chipipay.com/{version}"
+
+    def _add_version_params(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Add API version query parameters.
+
+        Args:
+            params: Existing parameters
+
+        Returns:
+            Parameters with version info added
+        """
+        if params is None:
+            params = {}
+        params["__chipi_api_version"] = API_VERSION_DATE
+        return params
+
+    def _get_headers(self, bearer_token: Optional[str] = None) -> Dict[str, str]:
+        """
+        Get HTTP headers for requests.
+
+        Args:
+            bearer_token: Optional bearer token for authentication
+
+        Returns:
+            Dictionary of headers
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": self.api_public_key,
+        }
+
+        if bearer_token:
+            headers["Authorization"] = f"Bearer {bearer_token}"
+
+        return headers
+
+    def get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        bearer_token: Optional[str] = None,
+    ) -> Any:
+        """
+        Synchronous GET request.
+
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+            bearer_token: Optional bearer token
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking parameters
+            params = self._add_version_params(params or {})
+            
+            # Filter out None values
+            params = {k: v for k, v in params.items() if v is not None}
+
+            response = self._sync_client.get(
+                url,
+                params=params,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    async def aget(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        bearer_token: Optional[str] = None,
+    ) -> Any:
+        """
+        Async GET request.
+
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+            bearer_token: Optional bearer token
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking parameters
+            params = self._add_version_params(params or {})
+            
+            # Filter out None values
+            params = {k: v for k, v in params.items() if v is not None}
+
+            response = await self._async_client.get(
+                url,
+                params=params,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    def post(
+        self,
+        endpoint: str,
+        bearer_token: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Synchronous POST request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+            body: Request body
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = self._sync_client.post(
+                url,
+                params=params,
+                json=body,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    async def apost(
+        self,
+        endpoint: str,
+        bearer_token: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Async POST request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+            body: Request body
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = await self._async_client.post(
+                url,
+                params=params,
+                json=body,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    def put(
+        self,
+        endpoint: str,
+        bearer_token: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Synchronous PUT request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+            body: Request body
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = self._sync_client.put(
+                url,
+                params=params,
+                json=body,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    async def aput(
+        self,
+        endpoint: str,
+        bearer_token: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Async PUT request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+            body: Request body
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = await self._async_client.put(
+                url,
+                params=params,
+                json=body,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    def delete(
+        self,
+        endpoint: str,
+        bearer_token: str,
+    ) -> Any:
+        """
+        Synchronous DELETE request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = self._sync_client.delete(
+                url,
+                params=params,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    async def adelete(
+        self,
+        endpoint: str,
+        bearer_token: str,
+    ) -> Any:
+        """
+        Async DELETE request.
+
+        Args:
+            endpoint: API endpoint path
+            bearer_token: Bearer token for authentication
+
+        Returns:
+            Response data
+
+        Raises:
+            ChipiApiError: If request fails
+        """
+        try:
+            url = f"{self.base_url}{endpoint}"
+            
+            # Add version tracking to URL
+            params = self._add_version_params({})
+
+            response = await self._async_client.delete(
+                url,
+                params=params,
+                headers=self._get_headers(bearer_token),
+            )
+
+            data = response.json()
+
+            if not response.is_success:
+                error_data = validate_error_response(data)
+                raise ChipiApiError(
+                    error_data["message"],
+                    error_data.get("code", f"HTTP_{response.status_code}"),
+                    response.status_code,
+                )
+
+            return data
+        except ChipiApiError:
+            raise
+        except Exception as error:
+            raise handle_api_error(error)
+
+    def close(self):
+        """Close the sync HTTP client."""
+        self._sync_client.close()
+
+    async def aclose(self):
+        """Close the async HTTP client."""
+        await self._async_client.aclose()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.aclose()

chipi_sdk/constants.py

@@ -0,0 +1,171 @@
+"""Constants used across Chipi SDK."""
+
+from typing import Optional
+from .models.wallet import WalletType
+
+
+# API Versioning
+API_VERSION = "1"
+API_VERSION_DATE = "2025-12-30"
+
+# Starknet Networks
+STARKNET_NETWORKS = {
+    "MAINNET": "https://starknet-mainnet.public.blastapi.io/rpc/v0_7",
+    "SEPOLIA": "https://starknet-sepolia.public.blastapi.io/rpc/v0_7",
+}
+
+# Contract Addresses
+CONTRACT_ADDRESSES = {
+    "USDC_MAINNET": "0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb",
+    "VESU_USDC_MAINNET": "0x017f19582c61479f2fe0b6606300e975c0a8f439102f43eeecc1d0e9b3d84350",
+}
+
+# Token Decimals
+TOKEN_DECIMALS = {
+    "USDC": 6,
+    "USDT": 6,
+    "ETH": 18,
+    "STRK": 18,
+    "DAI": 18,
+    "WBTC": 8,
+}
+
+# API Endpoints
+API_ENDPOINTS = {
+    "CHIPI_WALLETS": "/chipi-wallets",
+    "TRANSACTIONS": "/transactions",
+    "SKUS": "/skus",
+    "SKU_TRANSACTIONS": "/sku-transactions",
+    "EXCHANGES": "/exchanges",
+    "USERS": "/users",
+}
+
+# Default Pagination
+DEFAULT_PAGINATION = {
+    "PAGE": 1,
+    "LIMIT": 10,
+    "MAX_LIMIT": 100,
+}
+
+# Error Codes
+ERRORS = {
+    "INVALID_API_KEY": "INVALID_API_KEY",
+    "WALLET_NOT_FOUND": "WALLET_NOT_FOUND",
+    "INSUFFICIENT_BALANCE": "INSUFFICIENT_BALANCE",
+    "TRANSACTION_FAILED": "TRANSACTION_FAILED",
+    "INVALID_SIGNATURE": "INVALID_SIGNATURE",
+    "SKU_NOT_FOUND": "SKU_NOT_FOUND",
+    "SKU_UNAVAILABLE": "SKU_UNAVAILABLE",
+}
+
+# SKU Contracts
+SKU_CONTRACTS = {
+    "RECHARGER_WITH_STRK_MAINNET": "0x02d65bb726d2c29e3c97669cf297c5145eac19284fb6f935c05c0bfc68dae2b7",
+    "CHIPI_BILL_SERVICE": "0x4e8150110d580069de26adec9b179023289d55859ea07487aaade5458d7aa8b",
+}
+
+# Service Types
+SERVICE_TYPES = {
+    "BUY_SERVICE": "BUY_SERVICE",
+}
+
+# Carrier IDs
+CARRIER_IDS = {
+    "CHIPI_PAY": "chipi_pay",
+}
+
+# Chain Types
+CHAIN_TYPES = {
+    "STARKNET": "STARKNET",
+}
+
+# Chain Token Types
+CHAIN_TOKEN_TYPES = {
+    "USDC": "USDC",
+    "USDT": "USDT",
+    "ETH": "ETH",
+    "STRK": "STRK",
+    "DAI": "DAI",
+    "WBTC": "WBTC",
+    "OTHER": "OTHER",
+}
+
+# Wallet Class Hashes
+WALLET_CLASS_HASHES: dict[WalletType, str] = {
+    WalletType.CHIPI: "0x0484bbd2404b3c7264bea271f7267d6d4004821ac7787a9eed7f472e79ef40d1",  # v33 — latest, spending policy + audit fixes
+    WalletType.READY: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f",
+}
+
+# Previous CHIPI wallet class hashes still deployed on-chain (newest → oldest)
+LEGACY_CHIPI_CLASS_HASHES: list[str] = [
+    "0x035a2251aca25daba18a5d8950deffa8372a7d84774554e75283cb85552eebc9", # v32 — audit 3
+    "0x0254f6dd0427319ec614c29e4e3929500d1ba95d0da87ff81d67051ce572667",  # v31
+    "0x072b77b033a874fa1b8f7ff52e18be8fb5ce01a00c59cd184ae15f5b29bc0e57", # v30
+    "0x053f4f8791ed5bed0fddaa553d180c664e32cfaf8316bb232ae77bb08f459f2a", # v29 — previous default
+    "0x02de1565226d5215a38b68c4d9a4913989b54edff64c68c45e453c417b44cd83", # v28
+]
+
+
+def get_wallet_type_from_class_hash(class_hash: str) -> Optional[str]:
+    """
+    Determine wallet type from an on-chain class hash.
+
+    Args:
+        class_hash: Class hash to look up
+
+    Returns:
+        Wallet type string ("CHIPI" or "READY"), or None if unknown
+    """
+    def normalize(h: str) -> str:
+        import re
+        return re.sub(r"^0x0+", "0x", h.lower())
+
+    normalized = normalize(class_hash)
+
+    if normalize(WALLET_CLASS_HASHES[WalletType.READY]) == normalized:
+        return "READY"
+    if normalize(WALLET_CLASS_HASHES[WalletType.CHIPI]) == normalized:
+        return "CHIPI"
+    if any(normalize(h) == normalized for h in LEGACY_CHIPI_CLASS_HASHES):
+        return "CHIPI"
+    return None
+
+# RPC Endpoints per Wallet Type
+WALLET_RPC_ENDPOINTS: dict[WalletType, str] = {
+    WalletType.CHIPI: "https://starknet-mainnet.public.blastapi.io/rpc/v0_7",
+    WalletType.READY: "https://cloud.argent-api.com/v1/starknet/mainnet/rpc/v0.7",
+}
+
+# Paymaster Configuration
+PAYMASTER_CONFIG = {
+    "URL": "https://paymaster.chipipay.com",
+}
+
+# Session Key Configuration (CHIPI wallets only - SNIP-9 compatible)
+SESSION_DEFAULTS = {
+    "DURATION_SECONDS": 21600,  # Default session duration: 6 hours
+    "MAX_CALLS": 1000,  # Default max calls per session
+}
+
+# Session-specific Error Codes
+SESSION_ERRORS = {
+    "INVALID_WALLET_TYPE_FOR_SESSION": "INVALID_WALLET_TYPE_FOR_SESSION",
+    "SESSION_EXPIRED": "SESSION_EXPIRED",
+    "SESSION_NOT_REGISTERED": "SESSION_NOT_REGISTERED",
+    "SESSION_REVOKED": "SESSION_REVOKED",
+    "SESSION_MAX_CALLS_EXCEEDED": "SESSION_MAX_CALLS_EXCEEDED",
+    "SESSION_ENTRYPOINT_NOT_ALLOWED": "SESSION_ENTRYPOINT_NOT_ALLOWED",
+    "SESSION_DECRYPTION_FAILED": "SESSION_DECRYPTION_FAILED",
+    "SESSION_CREATION_FAILED": "SESSION_CREATION_FAILED",
+    "INVALID_SPENDING_POLICY": "INVALID_SPENDING_POLICY",
+}
+
+# Session Contract Entrypoint Names
+SESSION_ENTRYPOINTS = {
+    "ADD_OR_UPDATE": "add_or_update_session_key",
+    "REVOKE": "revoke_session_key",
+    "GET_DATA": "get_session_data",
+    "SET_SPENDING_POLICY": "set_spending_policy",
+    "GET_SPENDING_POLICY": "get_spending_policy",
+    "REMOVE_SPENDING_POLICY": "remove_spending_policy",
+}