airalo-sdk 1.0.0__py3-none-any.whl

airalo/helpers/crypt.py

@@ -0,0 +1,154 @@
+"""
+Encryption Helper Module
+
+This module handles encryption and decryption operations using the cryptography library.
+Provides equivalent functionality to PHP's sodium library.
+"""
+
+import base64
+import os
+from typing import Any, Union
+
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+from ..exceptions.airalo_exception import AiraloException
+
+
+class Crypt:
+    """
+    Encryption/decryption utility class.
+
+    Uses ChaCha20-Poly1305 for authenticated encryption, which is equivalent
+    to sodium's crypto_secretbox functionality.
+    """
+
+    # Constants matching sodium's requirements
+    KEY_BYTES = 32  # SODIUM_CRYPTO_SECRETBOX_KEYBYTES
+    NONCE_BYTES = 12  # For ChaCha20-Poly1305
+
+    @staticmethod
+    def encrypt(data: str, key: str) -> str:
+        """
+        Encrypt data using ChaCha20-Poly1305.
+
+        Args:
+            data: Plain text data to encrypt
+            key: Encryption key (will be truncated/padded to 32 bytes)
+
+        Returns:
+            Base64-encoded encrypted data with nonce prepended
+        """
+        if not data or not key:
+            return data
+
+        # Prepare key (ensure it's exactly 32 bytes)
+        key_bytes = Crypt._prepare_key(key)
+
+        # Check if data is already encrypted
+        if Crypt.is_encrypted(data):
+            return data
+
+        # Generate random nonce
+        nonce = os.urandom(Crypt.NONCE_BYTES)
+
+        # Create cipher and encrypt
+        cipher = ChaCha20Poly1305(key_bytes)
+        encrypted = cipher.encrypt(nonce, data.encode("utf-8"), None)
+
+        # Combine nonce and encrypted data, then base64 encode
+        combined = nonce + encrypted
+        return base64.b64encode(combined).decode("ascii")
+
+    @staticmethod
+    def decrypt(data: str, key: str) -> str:
+        """
+        Decrypt data encrypted with ChaCha20-Poly1305.
+
+        Args:
+            data: Base64-encoded encrypted data
+            key: Decryption key
+
+        Returns:
+            Decrypted plain text
+
+        Raises:
+            AiraloException: If decryption fails
+        """
+        if not data or not key:
+            return data
+
+        # Prepare key
+        key_bytes = Crypt._prepare_key(key)
+
+        # Check if data is encrypted
+        if not Crypt.is_encrypted(data):
+            return data
+
+        try:
+            # Decode from base64
+            encrypted = base64.b64decode(data)
+
+            # Extract nonce and ciphertext
+            nonce = encrypted[: Crypt.NONCE_BYTES]
+            ciphertext = encrypted[Crypt.NONCE_BYTES :]
+
+            # Decrypt
+            cipher = ChaCha20Poly1305(key_bytes)
+            decrypted = cipher.decrypt(nonce, ciphertext, None)
+
+            return decrypted.decode("utf-8")
+        except Exception as e:
+            raise AiraloException(f"Decryption failed: {e}")
+
+    @staticmethod
+    def is_encrypted(data: Any) -> bool:
+        """
+        Check if data appears to be encrypted.
+
+        Args:
+            data: Data to check
+
+        Returns:
+            True if data appears to be encrypted, False otherwise
+        """
+        # Check for non-string types
+        if not isinstance(data, str):
+            return False
+
+        # Check minimum length (nonce + some ciphertext + base64 overhead)
+        if len(data) < 56:
+            return False
+
+        # Check if it's numeric (encrypted data shouldn't be purely numeric)
+        if data.isdigit():
+            return False
+
+        # Check if it's valid base64
+        try:
+            decoded = base64.b64decode(data, validate=True)
+            # Verify we can encode it back to the same string
+            return base64.b64encode(decoded).decode("ascii") == data
+        except Exception:
+            return False
+
+    @staticmethod
+    def _prepare_key(key: str) -> bytes:
+        """
+        Prepare encryption key to be exactly 32 bytes.
+
+        Args:
+            key: Raw key string
+
+        Returns:
+            32-byte key
+        """
+        key_bytes = key.encode("utf-8")
+
+        # Truncate or pad to exactly 32 bytes
+        if len(key_bytes) > Crypt.KEY_BYTES:
+            return key_bytes[: Crypt.KEY_BYTES]
+        elif len(key_bytes) < Crypt.KEY_BYTES:
+            # Pad with zeros
+            return key_bytes.ljust(Crypt.KEY_BYTES, b"\0")
+
+        return key_bytes

airalo/helpers/date_helper.py

@@ -0,0 +1,12 @@
+# date_helper.py
+from datetime import datetime
+
+
+class DateHelper:
+    @staticmethod
+    def validate_date(date_str: str, date_format: str = "%Y-%m-%d") -> bool:
+        try:
+            datetime.strptime(date_str, date_format)
+            return True
+        except ValueError:
+            return False

airalo/helpers/signature.py

@@ -0,0 +1,119 @@
+"""
+Signature Helper Module
+
+This module handles HMAC signature generation for API authentication.
+"""
+
+import hashlib
+import hmac
+import json
+from typing import Any, Optional, Union
+
+
+class Signature:
+    """
+    Signature generator for API authentication.
+
+    Generates HMAC-SHA512 signatures for request payload validation.
+    """
+
+    def __init__(self, secret: str):
+        """
+        Initialize signature generator.
+
+        Args:
+            secret: Secret key for HMAC generation
+        """
+        self._secret = secret
+
+    def get_signature(self, payload: Any) -> Optional[str]:
+        """
+        Generate HMAC signature for payload.
+
+        Args:
+            payload: Request payload (dict, string, or any JSON-serializable object)
+
+        Returns:
+            HMAC-SHA512 signature as hex string, or None if payload is empty
+        """
+        prepared_payload = self._prepare_payload(payload)
+        if not prepared_payload:
+            return None
+
+        return self._sign_data(prepared_payload)
+
+    def check_signature(self, hash_value: Optional[str], payload: Any) -> bool:
+        """
+        Verify HMAC signature.
+
+        Args:
+            hash_value: Expected signature
+            payload: Request payload
+
+        Returns:
+            True if signature matches, False otherwise
+        """
+        if not hash_value:
+            return False
+
+        prepared_payload = self._prepare_payload(payload)
+        if not prepared_payload:
+            return False
+
+        expected_signature = self._sign_data(prepared_payload)
+        return hmac.compare_digest(expected_signature, hash_value)
+
+    def _prepare_payload(self, payload: Any) -> Optional[str]:
+        """
+        Prepare payload for signing.
+
+        Args:
+            payload: Raw payload
+
+        Returns:
+            JSON string representation of payload, or None if empty
+        """
+        if not payload:
+            return None
+
+        if isinstance(payload, str):
+            # If it's already a string, ensure it's valid JSON by parsing and re-encoding
+            try:
+                payload = self._escape_forward_slashes(payload)
+
+                # Remove whitespaces by parsing and re-encoding
+                parsed = json.loads(payload)
+                return json.dumps(parsed, separators=(",", ":"), ensure_ascii=False)
+            except json.JSONDecodeError:
+                # If not valid JSON, return as is
+                return payload
+
+        # Convert to JSON string
+        try:
+            json_encoded = json.dumps(
+                payload, separators=(",", ":"), ensure_ascii=False
+            )
+            return self._escape_forward_slashes(json_encoded)
+        except (TypeError, ValueError):
+            # If not JSON-serializable, convert to string
+            return str(payload)
+
+    def _escape_forward_slashes(self, payload: str) -> str:
+        return payload.replace("/", "\\/")
+
+    def _sign_data(self, payload: str, algo: str = "sha512") -> str:
+        """
+        Generate HMAC signature.
+
+        Args:
+            payload: Prepared payload string
+            algo: Hash algorithm (default: sha512)
+
+        Returns:
+            HMAC signature as hex string
+        """
+        return hmac.new(
+            self._secret.encode("utf-8"),
+            payload.encode("utf-8"),
+            getattr(hashlib, algo),
+        ).hexdigest()

airalo/resources/__init__.py

@@ -0,0 +1,8 @@
+"""
+HTTP resources for Airalo SDK.
+"""
+
+from .http_resource import HttpResource
+from .multi_http_resource import MultiHttpResource
+
+__all__ = ["HttpResource", "MultiHttpResource"]

airalo/resources/http_resource.py

@@ -0,0 +1,324 @@
+"""
+HTTP Resource Module
+
+This module provides HTTP client functionality using urllib for making API requests.
+"""
+
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Tuple, Union
+from urllib.parse import urlencode
+
+from ..config import Config
+from ..constants.sdk_constants import SdkConstants
+from ..exceptions.airalo_exception import NetworkError
+
+
+class HttpResource:
+    """
+    HTTP client for making API requests.
+
+    Uses urllib for HTTP operations with support for GET, POST, and HEAD methods.
+    """
+
+    def __init__(self, config: Config, get_handler: bool = False):
+        """
+        Initialize HTTP resource.
+
+        Args:
+            config: SDK configuration
+            get_handler: If True, return request object instead of executing
+
+        Raises:
+            NetworkError: If urllib is not available
+        """
+        self._config = config
+        self._get_handler = get_handler
+        self._ignore_ssl = False
+        self._timeout = SdkConstants.DEFAULT_TIMEOUT
+        self._rfc = 1  # Default to RFC1738 for query encoding
+
+        # Response attributes
+        self.header: str = ""
+        self.code: int = 0
+        self.response_headers: Dict[str, str] = {}
+
+        # Request headers
+        self._request_headers: Dict[str, str] = {}
+        self._default_headers: Dict[str, str] = {
+            "User-Agent": f"Airalo-Python-SDK/{SdkConstants.VERSION}",
+            "airalo-python-sdk": f"{SdkConstants.VERSION}",
+            "Accept": "application/json",
+        }
+
+        # Initialize headers
+        self._init_headers()
+
+    def get(
+        self, url: str, params: Optional[Dict[str, Any]] = None
+    ) -> Union[str, urllib.request.Request]:
+        """
+        Perform GET request.
+
+        Args:
+            url: Request URL
+            params: Query parameters
+
+        Returns:
+            Response body as string or request object if get_handler is True
+        """
+        if params:
+            # Build query string
+            query_string = self._build_query_string(params)
+            url = f"{url.rstrip('?')}?{query_string}"
+
+        return self._request(url, method="GET")
+
+    def post(
+        self, url: str, params: Optional[Union[Dict[str, Any], str]] = None
+    ) -> Union[str, urllib.request.Request]:
+        """
+        Perform POST request.
+
+        Args:
+            url: Request URL
+            params: Request body (dict or string)
+
+        Returns:
+            Response body as string or request object if get_handler is True
+        """
+        data = None
+
+        if params:
+            if isinstance(params, dict):
+                # Check if we should send as JSON or form data
+                if (
+                    "Content-Type" in self._request_headers
+                    and "json" in self._request_headers["Content-Type"]
+                ):
+                    data = json.dumps(params).encode("utf-8")
+                else:
+                    data = urlencode(params).encode("utf-8")
+            else:
+                # Assume it's already a string (could be JSON or form-encoded)
+                data = params.encode("utf-8") if isinstance(params, str) else params
+
+        return self._request(url, data=data, method="POST")
+
+    def head(
+        self, url: str, params: Optional[Dict[str, Any]] = None
+    ) -> Union[str, urllib.request.Request]:
+        """
+        Perform HEAD request.
+
+        Args:
+            url: Request URL
+            params: Query parameters
+
+        Returns:
+            Response headers as string or request object if get_handler is True
+        """
+        if params:
+            query_string = self._build_query_string(params)
+            url = f"{url.rstrip('?')}?{query_string}"
+
+        return self._request(url, method="HEAD")
+
+    def set_headers(self, headers: Union[Dict[str, str], List[str]]) -> "HttpResource":
+        """
+        Set additional request headers.
+
+        Args:
+            headers: Dictionary or list of header strings
+
+        Returns:
+            Self for method chaining
+        """
+        if isinstance(headers, list):
+            # Parse list of header strings
+            for header in headers:
+                if ":" in header:
+                    key, value = header.split(":", 1)
+                    self._request_headers[key.strip()] = value.strip()
+        else:
+            # Merge dictionary
+            self._request_headers.update(headers)
+
+        return self
+
+    def set_timeout(self, timeout: int = 30) -> "HttpResource":
+        """
+        Set request timeout.
+
+        Args:
+            timeout: Timeout in seconds
+
+        Returns:
+            Self for method chaining
+        """
+        self._timeout = timeout
+        return self
+
+    def ignore_ssl(self) -> "HttpResource":
+        """
+        Ignore SSL certificate verification.
+
+        Returns:
+            Self for method chaining
+        """
+        self._ignore_ssl = True
+        return self
+
+    def use_rfc(self, rfc: int) -> "HttpResource":
+        """
+        Set RFC standard for URL encoding.
+
+        Args:
+            rfc: RFC standard (1 for RFC1738, 3 for RFC3986)
+
+        Returns:
+            Self for method chaining
+        """
+        self._rfc = rfc
+        return self
+
+    def set_basic_authentication(
+        self, username: str, password: str = ""
+    ) -> "HttpResource":
+        """
+        Set HTTP basic authentication.
+
+        Args:
+            username: Username
+            password: Password
+
+        Returns:
+            Self for method chaining
+        """
+        import base64
+
+        credentials = base64.b64encode(f"{username}:{password}".encode()).decode(
+            "ascii"
+        )
+        self._request_headers["Authorization"] = f"Basic {credentials}"
+        return self
+
+    def _request(
+        self, url: str, data: Optional[bytes] = None, method: str = "GET"
+    ) -> Union[str, urllib.request.Request]:
+        """
+        Execute HTTP request.
+
+        Args:
+            url: Request URL
+            data: Request body
+            method: HTTP method
+
+        Returns:
+            Response body or request object
+
+        Raises:
+            NetworkError: If request fails
+        """
+        # Create request object
+        request = urllib.request.Request(url, data=data, method=method)
+
+        # Add headers
+        for key, value in self._request_headers.items():
+            request.add_header(key, value)
+
+        # Return request object if handler mode
+        if self._get_handler:
+            return request
+
+        # Configure SSL context
+        context = None
+        if self._ignore_ssl:
+            context = ssl.create_default_context()
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+
+        try:
+            # Execute request
+            response = urllib.request.urlopen(
+                request, timeout=self._timeout, context=context
+            )
+
+            # Read response
+            response_body = response.read().decode("utf-8")
+
+            # Store response details
+            self.code = response.getcode()
+            self.response_headers = dict(response.headers)
+            self.header = str(response.headers)
+
+            # Reset for next request
+            self._reset()
+
+            return response_body
+
+        except urllib.error.HTTPError as e:
+            # HTTP error (4xx, 5xx)
+            self.code = e.code
+            self.response_headers = dict(e.headers)
+            self.header = str(e.headers)
+
+            # Try to read error response
+            try:
+                error_body = e.read().decode("utf-8")
+                self._reset()
+                return error_body
+            except:
+                self._reset()
+                raise NetworkError(f"HTTP {e.code}: {e.reason}", http_status=e.code)
+
+        except urllib.error.URLError as e:
+            # Network error
+            self._reset()
+            raise NetworkError(f"Network error: {e.reason}")
+
+        except Exception as e:
+            # Other errors
+            self._reset()
+            raise NetworkError(f"Request failed: {str(e)}")
+
+    def _init_headers(self) -> None:
+        """Initialize request headers with defaults and config headers."""
+        self._request_headers = self._default_headers.copy()
+
+        # Add custom headers from config
+        config_headers = self._config.get_http_headers()
+        if isinstance(config_headers, list):
+            for header in config_headers:
+                if ":" in header:
+                    key, value = header.split(":", 1)
+                    self._request_headers[key.strip()] = value.strip()
+        elif isinstance(config_headers, dict):
+            self._request_headers.update(config_headers)
+
+    def _reset(self) -> None:
+        """Reset headers and state for next request."""
+        self._init_headers()
+        self._ignore_ssl = False
+        self._timeout = SdkConstants.DEFAULT_TIMEOUT
+
+    def _build_query_string(self, params: Dict[str, Any]) -> str:
+        """
+        Build query string from parameters.
+
+        Args:
+            params: Query parameters
+
+        Returns:
+            URL-encoded query string
+        """
+        # Use appropriate encoding based on RFC setting
+        if self._rfc == 3:
+            # RFC3986 - uses %20 for spaces
+            return urlencode(params, quote_via=urllib.parse.quote)
+        else:
+            # RFC1738 - uses + for spaces (default)
+            return urlencode(params)