airalo-sdk 1.0.0__py3-none-any.whl

airalo/config.py

@@ -0,0 +1,146 @@
+"""
+Configuration Module
+
+This module handles SDK configuration including credentials, environment settings,
+and HTTP headers.
+"""
+
+import json
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urlencode
+
+from .constants.api_constants import ApiConstants
+from .exceptions.airalo_exception import ConfigurationError
+
+
+class Config:
+    """
+    Configuration class for Airalo SDK.
+
+    Handles SDK configuration including API credentials, environment selection,
+    and custom HTTP headers.
+    """
+
+    MANDATORY_CONFIG_KEYS = [
+        "client_id",
+        "client_secret",
+    ]
+
+    def __init__(self, data: Union[Dict[str, Any], str, object]):
+        """
+        Initialize configuration.
+
+        Args:
+            data: Configuration data as dict, JSON string, or object with attributes
+
+        Raises:
+            ConfigurationError: If configuration is invalid or missing required fields
+        """
+        self._data: Dict[str, Any] = {}
+
+        if not data:
+            raise ConfigurationError("Config data is not provided")
+
+        # Convert different input types to dictionary
+        if isinstance(data, str):
+            try:
+                self._data = json.loads(data)
+            except json.JSONDecodeError as e:
+                raise ConfigurationError(f"Invalid JSON config data: {e}")
+        elif isinstance(data, dict):
+            self._data = data.copy()
+        elif hasattr(data, "__dict__"):
+            # Convert object to dictionary
+            self._data = vars(data).copy()
+        else:
+            try:
+                # Try to serialize and deserialize to get a dict
+                self._data = json.loads(json.dumps(data, default=lambda o: o.__dict__))
+            except (TypeError, json.JSONDecodeError) as e:
+                raise ConfigurationError(f"Invalid config data provided: {e}")
+
+        self._validate()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value by key.
+
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default
+        """
+        return self._data.get(key, default)
+
+    def get_config(self) -> Dict[str, Any]:
+        """
+        Get complete configuration dictionary.
+
+        Returns:
+            Configuration dictionary
+        """
+        return self._data.copy()
+
+    def get_credentials(self, as_string: bool = False) -> Union[Dict[str, str], str]:
+        """
+        Get API credentials.
+
+        Args:
+            as_string: If True, return as URL-encoded string
+
+        Returns:
+            Credentials as dictionary or URL-encoded string
+        """
+        credentials = {
+            "client_id": self._data["client_id"],
+            "client_secret": self._data["client_secret"],
+        }
+
+        if as_string:
+            return urlencode(credentials)
+
+        return credentials
+
+    def get_environment(self) -> str:
+        """
+        Get current environment.
+        """
+        return self._data.get("env", "production")
+
+    def get_url(self) -> str:
+        """
+        Get base API URL for current environment.
+
+        Returns:
+            Base API URL
+        """
+        return ApiConstants.PRODUCTION_URL
+
+    def get_http_headers(self) -> List[str]:
+        """
+        Get custom HTTP headers.
+
+        Returns:
+            List of HTTP header strings
+        """
+        return self._data.get("http_headers", [])
+
+    def _validate(self) -> None:
+        """
+        Validate configuration.
+
+        Raises:
+            ConfigurationError: If configuration is invalid
+        """
+        # Check mandatory fields
+        for key in self.MANDATORY_CONFIG_KEYS:
+            if key not in self._data or not self._data[key]:
+                raise ConfigurationError(
+                    f"Mandatory field `{key}` is missing in the provided config data"
+                )
+
+        # Set default environment if not provided
+        if "env" not in self._data:
+            self._data["env"] = "production"

airalo/constants/__init__.py

@@ -0,0 +1,8 @@
+"""
+Constants package for Airalo SDK.
+"""
+
+from .api_constants import ApiConstants
+from .sdk_constants import SdkConstants
+
+__all__ = ["ApiConstants", "SdkConstants"]

airalo/constants/api_constants.py

@@ -0,0 +1,49 @@
+"""
+API Constants Module
+
+This module contains all API endpoints and URLs used by the Airalo SDK.
+"""
+
+
+class ApiConstants:
+    """API endpoints and URLs for Airalo SDK."""
+
+    PRODUCTION_URL = "https://partners-api.airalo.com/v2/"
+
+    # Authentication
+    TOKEN_SLUG = "token"
+
+    # Package endpoints
+    PACKAGES_SLUG = "packages"
+
+    # Order endpoints
+    ORDERS_SLUG = "orders"
+    ASYNC_ORDERS_SLUG = "orders-async"
+    TOPUPS_SLUG = "orders/topups"
+
+    # Voucher endpoints
+    VOUCHERS_SLUG = "voucher/airmoney"
+    VOUCHERS_ESIM_SLUG = "voucher/esim"
+
+    # SIM endpoints
+    SIMS_SLUG = "sims"
+    SIMS_USAGE = "usage"
+    SIMS_TOPUPS = "topups"
+    SIMS_PACKAGES = "packages"
+
+    # Instructions and compatibility
+    INSTRUCTIONS_SLUG = "instructions"
+    COMPATIBILITY_SLUG = "compatible-devices-lite"
+
+    # Finance endpoints
+    EXCHANGE_RATES_SLUG = "finance/exchange-rates"
+
+    # Future orders
+    FUTURE_ORDERS = "future-orders"
+    CANCEL_FUTURE_ORDERS = "cancel-future-orders"
+
+    # Catalog
+    OVERRIDE_SLUG = "packages/overrides"
+
+    # Notifications
+    NOTIFICATIONS_SLUG = "notifications"

airalo/constants/sdk_constants.py

@@ -0,0 +1,32 @@
+"""
+SDK Constants Module
+
+This module contains SDK-specific constants such as version, limits, and timeouts.
+"""
+
+
+class SdkConstants:
+    """SDK-specific constants for Airalo SDK."""
+
+    # SDK Version
+    VERSION = "1.0.0"
+
+    # Order limits
+    BULK_ORDER_LIMIT = 50
+    ORDER_LIMIT = 50
+    FUTURE_ORDER_LIMIT = 50
+
+    # Voucher limits
+    VOUCHER_MAX_NUM = 100000
+    VOUCHER_MAX_QUANTITY = 100
+
+    # HTTP settings
+    DEFAULT_TIMEOUT = 60  # seconds
+    DEFAULT_RETRY_COUNT = 2
+
+    # Cache settings
+    DEFAULT_CACHE_TTL = 3600  # 1 hour in seconds
+    TOKEN_CACHE_TTL = 3600  # 1 hour in seconds
+
+    # Concurrency settings
+    MAX_CONCURRENT_REQUESTS = 5

airalo/exceptions/__init__.py

@@ -0,0 +1,21 @@
+"""
+Exceptions package for Airalo SDK.
+"""
+
+from .airalo_exception import (
+    AiraloException,
+    ConfigurationError,
+    AuthenticationError,
+    ValidationError,
+    APIError,
+    NetworkError,
+)
+
+__all__ = [
+    "AiraloException",
+    "ConfigurationError",
+    "AuthenticationError",
+    "ValidationError",
+    "APIError",
+    "NetworkError",
+]

airalo/exceptions/airalo_exception.py

@@ -0,0 +1,64 @@
+"""
+Airalo Exception Module
+
+This module defines custom exceptions for the Airalo SDK.
+"""
+
+
+class AiraloException(Exception):
+    """
+    Base exception class for Airalo SDK.
+
+    This exception is raised when SDK-specific errors occur,
+    such as configuration errors, API errors, or validation errors.
+    """
+
+    def __init__(self, message: str, error_code: str = None, http_status: int = None):
+        """
+        Initialize AiraloException.
+
+        Args:
+            message: Error message describing the exception
+            error_code: Optional error code from API
+            http_status: Optional HTTP status code
+        """
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.http_status = http_status
+
+    def __str__(self) -> str:
+        """Return string representation of the exception."""
+        if self.error_code:
+            return f"[{self.error_code}] {self.message}"
+        return self.message
+
+
+class ConfigurationError(AiraloException):
+    """Exception raised for configuration-related errors."""
+
+    pass
+
+
+class AuthenticationError(AiraloException):
+    """Exception raised for authentication failures."""
+
+    pass
+
+
+class ValidationError(AiraloException):
+    """Exception raised for validation errors."""
+
+    pass
+
+
+class APIError(AiraloException):
+    """Exception raised for API-related errors."""
+
+    pass
+
+
+class NetworkError(AiraloException):
+    """Exception raised for network-related errors."""
+
+    pass

airalo/helpers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Helper utilities for Airalo SDK.
+"""
+
+from .cached import Cached
+from .crypt import Crypt
+from .signature import Signature
+
+__all__ = ["Cached", "Crypt", "Signature"]

airalo/helpers/cached.py

@@ -0,0 +1,177 @@
+"""
+Caching Helper Module
+
+This module provides file-based caching functionality for the SDK.
+"""
+
+import hashlib
+import os
+import pickle
+import tempfile
+import time
+from ..constants.sdk_constants import SdkConstants
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+
+class Cached:
+    """
+    File-based caching utility.
+
+    Provides simple file-based caching with TTL support using
+    project root cache directory.
+    """
+
+    CACHE_KEY_PREFIX = "airalo_"
+
+    _cache_path: Optional[Path] = None
+    _cache_name: str = ""
+
+    @classmethod
+    def get(
+        cls, work: Union[Callable[[], Any], Any], cache_name: str, ttl: int = 0
+    ) -> Any:
+        """
+        Get cached value or compute and cache it.
+
+        Args:
+            work: Callable that produces the value, or the value itself
+            cache_name: Unique name for this cache entry
+            ttl: Time-to-live in seconds (0 uses default)
+
+        Returns:
+            Cached or computed value
+        """
+        cls._init(cache_name)
+
+        cache_id = cls._get_id(cache_name)
+
+        # Try to get from cache
+        cached_result = cls._cache_get(cache_id, ttl)
+        if cached_result is not None:
+            return cached_result
+
+        # Compute result
+        if callable(work):
+            result = work()
+        else:
+            result = work
+
+        # Cache and return
+        return cls._cache_this(cache_id, result)
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clear all cache files."""
+        cls._init()
+
+        # Find and remove all cache files
+        cache_pattern = cls._cache_path / f"{cls.CACHE_KEY_PREFIX}*"
+        for cache_file in cls._cache_path.glob(f"{cls.CACHE_KEY_PREFIX}*"):
+            try:
+                cache_file.unlink()
+            except OSError:
+                pass  # Ignore errors when deleting cache files
+
+    @classmethod
+    def _init(cls, cache_name: str = "") -> None:
+        """
+        Initialize cache directory and name.
+
+        Args:
+            cache_name: Optional cache name to set
+        """
+        if cls._cache_path is None:
+            # Use project root cache directory
+            cls._cache_path = Path(__file__).resolve().parent.parent.parent / ".cache"
+            cls._cache_path.mkdir(parents=True, exist_ok=True)
+
+        if cache_name:
+            cls._cache_name = cache_name
+
+    @classmethod
+    def _get_id(cls, key: str) -> str:
+        """
+        Generate cache file ID from key.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cache file ID
+        """
+        return cls.CACHE_KEY_PREFIX + hashlib.md5(key.encode()).hexdigest()
+
+    @classmethod
+    def _cache_get(cls, cache_id: str, custom_ttl: int = 0) -> Optional[Any]:
+        """
+        Retrieve value from cache if valid.
+
+        Args:
+            cache_id: Cache file ID
+            custom_ttl: Custom TTL in seconds
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        cache_file = cls._cache_path / cache_id
+
+        if not cache_file.exists():
+            return None
+
+        # Check TTL
+        now = time.time()
+        file_mtime = cache_file.stat().st_mtime
+        ttl = custom_ttl if custom_ttl > 0 else SdkConstants.DEFAULT_CACHE_TTL
+
+        if now - file_mtime > ttl:
+            # Cache expired, remove file
+            try:
+                cache_file.unlink()
+            except OSError:
+                return None
+
+        # Read cached data
+        try:
+            with open(cache_file, "rb") as f:
+                return pickle.load(f)
+        except (OSError, pickle.PickleError):
+            # Corrupted cache file, remove it
+            try:
+                cache_file.unlink()
+            except OSError:
+                return None
+
+    @classmethod
+    def _cache_this(cls, cache_id: str, result: Any) -> Any:
+        """
+        Store value in cache.
+
+        Args:
+            cache_id: Cache file ID
+            result: Value to cache
+
+        Returns:
+            The cached value
+        """
+        if result is None:
+            return None
+
+        cache_file = cls._cache_path / cache_id
+
+        try:
+            # Write cache file
+            with open(cache_file, "wb") as f:
+                pickle.dump(result, f)
+
+            # Try to set permissions (may fail on some systems)
+            try:
+                cache_file.chmod(0o666)
+            except OSError:
+                pass  # Ignore permission errors
+
+        except (OSError, pickle.PickleError) as e:
+            # Failed to cache, but return the result anyway
+            pass
+
+        return result

airalo/helpers/cloud_sim_share_validator.py

@@ -0,0 +1,89 @@
+"""
+Cloud SIM Share Validator
+
+Helper class for validating SIM cloud sharing data.
+"""
+
+import re
+import json
+from typing import Any, Dict, List
+
+from ..exceptions.airalo_exception import AiraloException
+
+
+class CloudSimShareValidator:
+    """
+    Validator for SIM cloud sharing payloads.
+    """
+
+    _email_regex = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
+    _allowed_sharing_options = {"link", "pdf"}
+
+    @staticmethod
+    def validate(
+        sim_cloud_share: Dict[str, Any], required_fields: List[str] = None
+    ) -> bool:
+        """
+        Validate the SIM cloud sharing payload.
+
+        Args:
+            sim_cloud_share: The payload dictionary.
+            required_fields: List of required fields to validate.
+
+        Raises:
+            AiraloException: If validation fails.
+
+        Returns:
+            True if valid.
+        """
+        required_fields = required_fields or []
+
+        CloudSimShareValidator._check_required_fields(sim_cloud_share, required_fields)
+
+        # Validate 'to_email'
+        to_email = sim_cloud_share.get("to_email")
+        if to_email and not CloudSimShareValidator._email_regex.match(to_email):
+            raise AiraloException(
+                f"The to_email must be a valid email address, payload: {json.dumps(sim_cloud_share)}"
+            )
+
+        # Validate 'sharing_option'
+        for option in sim_cloud_share.get("sharing_option", []):
+            if option not in CloudSimShareValidator._allowed_sharing_options:
+                allowed = " or ".join(CloudSimShareValidator._allowed_sharing_options)
+                raise AiraloException(
+                    f"The sharing_option may be {allowed} or both, payload: {json.dumps(sim_cloud_share)}"
+                )
+
+        # Validate 'copy_address' emails
+        for cc_email in sim_cloud_share.get("copy_address", []):
+            if not CloudSimShareValidator._email_regex.match(cc_email):
+                raise AiraloException(
+                    f"The copy_address: {cc_email} must be a valid email address, payload: {json.dumps(sim_cloud_share)}"
+                )
+
+        return True
+
+    @staticmethod
+    def _check_required_fields(
+        sim_cloud_share: Dict[str, Any], required_fields: List[str]
+    ) -> bool:
+        """
+        Ensure required fields exist and are not empty.
+
+        Args:
+            sim_cloud_share: Payload dictionary.
+            required_fields: List of required keys.
+
+        Raises:
+            AiraloException: If a required field is missing or empty.
+
+        Returns:
+            True if all required fields are present.
+        """
+        for field in required_fields:
+            if not sim_cloud_share.get(field):
+                raise AiraloException(
+                    f"The {field} field is required, payload: {json.dumps(sim_cloud_share)}"
+                )
+        return True