virtualsmslabs 1.0.0__py3-none-any.whl

virtualsms/__init__.py

@@ -0,0 +1,34 @@
+from virtualsms.client import VirtualSMSClient
+from virtualsms.constants import ActivationStatus, PoolProvider
+from virtualsms.exceptions import (
+    ActivationException,
+    AuthenticationException,
+    InsufficientBalanceException,
+    NoNumbersException,
+    RateLimitException,
+    ServerException,
+    ValidationException,
+    VirtualSMSException,
+)
+from virtualsms.response import BalanceResponse, NumberResponse, StatusResponse
+from virtualsms.transport import Response, Transport, UrllibTransport
+
+__all__ = [
+    "VirtualSMSClient",
+    "ActivationStatus",
+    "PoolProvider",
+    "VirtualSMSException",
+    "AuthenticationException",
+    "InsufficientBalanceException",
+    "NoNumbersException",
+    "ValidationException",
+    "ActivationException",
+    "RateLimitException",
+    "ServerException",
+    "BalanceResponse",
+    "NumberResponse",
+    "StatusResponse",
+    "Transport",
+    "UrllibTransport",
+    "Response",
+]

virtualsms/client.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import hashlib
+import platform
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Type
+from urllib.parse import urlencode
+
+from virtualsms.constants import PoolProvider
+from virtualsms.exceptions import VirtualSMSException
+from virtualsms.parser import TextResponseParser
+from virtualsms.response import BalanceResponse, NumberResponse, StatusResponse
+from virtualsms.transport import Response, Transport, UrllibTransport
+
+
+class VirtualSMSClient:
+    VERSION = "1.0.0"
+    SDK_LANGUAGE = "python"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.virtualsms.de",
+        transport: Optional[Transport] = None,
+    ):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._transport = transport if transport is not None else UrllibTransport()
+        self._parser = TextResponseParser()
+        self._machine_id = hashlib.sha256(
+            (platform.platform() + sys.implementation.name).encode("utf-8")
+        ).hexdigest()[:32]
+
+    def get_balance(self) -> BalanceResponse:
+        response = self._call_api("getBalance")
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return BalanceResponse(balance=parsed.data["balance"])
+
+    def get_countries(self, pool_provider: Optional[str] = None) -> Dict[str, Any]:
+        response = self._call_api("getCountries", {"poolProvider": pool_provider})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_services_list(
+        self,
+        country: Optional[int] = None,
+        lang: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        response = self._call_api(
+            "getServicesList",
+            {"country": country, "lang": lang},
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_operators(
+        self,
+        country: int,
+        pool_provider: Optional[str] = None,
+    ) -> List[str]:
+        response = self._call_api(
+            "getOperators",
+            {"country": country, "poolProvider": pool_provider},
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        decoded = parsed.data["decoded"]
+        return decoded.get("countryOperators", decoded)
+
+    def get_prices(
+        self,
+        service: Optional[str] = None,
+        country: Optional[int] = None,
+        pool_provider: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        response = self._call_api(
+            "getPrices",
+            {"service": service, "country": country, "poolProvider": pool_provider},
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_prices_extended(
+        self,
+        service: Optional[str] = None,
+        country: Optional[int] = None,
+        free_price: Optional[bool] = None,
+        pool_provider: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        response = self._call_api(
+            "getPricesExtended",
+            {
+                "service": service,
+                "country": country,
+                "freePrice": "true" if free_price is True else ("false" if free_price is False else None),
+                "poolProvider": pool_provider,
+            },
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_prices_verification(
+        self,
+        service: Optional[str] = None,
+        pool_provider: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        response = self._call_api(
+            "getPricesVerification",
+            {"service": service, "poolProvider": pool_provider},
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_numbers_status(
+        self,
+        country: int,
+        operator: Optional[str] = None,
+        pool_provider: Optional[str] = None,
+    ) -> Dict[str, int]:
+        response = self._call_api(
+            "getNumbersStatus",
+            {"country": country, "operator": operator, "poolProvider": pool_provider},
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_number(
+        self,
+        service: str,
+        country: int,
+        max_price: Optional[float] = None,
+        operator: Optional[str] = None,
+        phone_exception: Optional[str] = None,
+        forward: Optional[bool] = None,
+        activation_type: Optional[int] = None,
+        language: Optional[str] = None,
+        use_cashback: Optional[bool] = None,
+        user_id: Optional[str] = None,
+        ref: Optional[str] = None,
+        pool_provider: Optional[str] = None,
+    ) -> NumberResponse:
+        response = self._call_api(
+            "getNumber",
+            {
+                "service": service,
+                "country": country,
+                "maxPrice": max_price,
+                "operator": operator,
+                "phoneException": phone_exception,
+                "forward": "1" if forward is True else ("0" if forward is False else None),
+                "activationType": activation_type,
+                "language": language,
+                "useCashBack": "true" if use_cashback is True else ("false" if use_cashback is False else None),
+                "userId": user_id,
+                "ref": ref,
+                "poolProvider": pool_provider,
+            },
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return NumberResponse(
+            activation_id=parsed.data["activation_id"],
+            phone_number=parsed.data["phone_number"],
+        )
+
+    def get_number_v2(
+        self,
+        service: str,
+        country: int,
+        max_price: Optional[float] = None,
+        operator: Optional[str] = None,
+        phone_exception: Optional[str] = None,
+        forward: Optional[bool] = None,
+        activation_type: Optional[int] = None,
+        language: Optional[str] = None,
+        use_cashback: Optional[bool] = None,
+        user_id: Optional[str] = None,
+        ref: Optional[str] = None,
+        order_id: Optional[str] = None,
+        pool_provider: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        response = self._call_api(
+            "getNumberV2",
+            {
+                "service": service,
+                "country": country,
+                "maxPrice": max_price,
+                "operator": operator,
+                "phoneException": phone_exception,
+                "forward": "1" if forward is True else ("0" if forward is False else None),
+                "activationType": activation_type,
+                "language": language,
+                "useCashBack": "true" if use_cashback is True else ("false" if use_cashback is False else None),
+                "userId": user_id,
+                "ref": ref,
+                "orderId": order_id,
+                "poolProvider": pool_provider,
+            },
+        )
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def set_status(self, id: int, status: int) -> str:
+        response = self._call_api("setStatus", {"id": id, "status": status})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["status"]
+
+    def get_status(self, id: int) -> StatusResponse:
+        response = self._call_api("getStatus", {"id": id})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return StatusResponse(
+            status=parsed.data["status"],
+            code=parsed.data.get("code"),
+            sms_text=parsed.data.get("sms_text"),
+        )
+
+    def get_status_v2(self, id: int) -> Dict[str, Any]:
+        response = self._call_api("getStatusV2", {"id": id})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_active_activations(self) -> List[Dict[str, Any]]:
+        response = self._call_api("getActiveActivations")
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        decoded = parsed.data["decoded"]
+        return decoded.get("activeActivations", [])
+
+    def check_extra_activation(self, id: int) -> Dict[str, Any]:
+        response = self._call_api("checkExtraActivation", {"id": id})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_extra_activation(self, id: int) -> NumberResponse:
+        response = self._call_api("getExtraActivation", {"id": id})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return NumberResponse(
+            activation_id=parsed.data["activation_id"],
+            phone_number=parsed.data["phone_number"],
+        )
+
+    def get_top_countries_by_service(self, service: str) -> List[Dict[str, Any]]:
+        response = self._call_api("getListOfTopCountriesByService", {"service": service})
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def get_notifications(self) -> Dict[str, Any]:
+        response = self._call_api("getNotifications")
+        parsed = self._parser.parse(response.body)
+        self._ensure_success(parsed, response)
+        return parsed.data["decoded"]
+
+    def _call_api(self, action: str, params: Optional[Dict[str, Any]] = None) -> Response:
+        query_params: Dict[str, Any] = {"api_key": self._api_key, "action": action}
+        if params:
+            for key, value in params.items():
+                if value is not None:
+                    query_params[key] = value
+
+        url = self._base_url + "/stubs/handler_api?" + urlencode(query_params)
+        headers = self._build_headers()
+        return self._transport.send(url, headers)
+
+    def _build_headers(self) -> Dict[str, str]:
+        return {
+            "X-SDK-Version": self.VERSION,
+            "X-SDK-Language": self.SDK_LANGUAGE,
+            "X-SDK-Machine-Id": self._machine_id,
+            "X-SDK-Timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def _ensure_success(self, parsed, response: Response) -> None:
+        if not parsed.is_success:
+            retry_after = None
+            if response.headers.get("Retry-After"):
+                retry_after = int(response.headers["Retry-After"])
+            raise VirtualSMSException.from_error_code(
+                error_code=parsed.error_code or "UNKNOWN",
+                http_status=response.status_code,
+                retry_after=retry_after,
+            )

virtualsms/constants.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+
+class ActivationStatus:
+    READY = 1
+    RETRY = 3
+    COMPLETE = 6
+    CANCEL = 8
+
+
+class PoolProvider:
+    ALPHA = "alpha"
+    PRIME = "prime"
+    GAMMA = "gamma"
+    ZETA = "zeta"

virtualsms/exceptions.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class VirtualSMSException(Exception):
+    def __init__(
+        self,
+        message: str,
+        error_code: str,
+        http_status: int,
+        retry_after: Optional[int] = None,
+    ):
+        super().__init__(message)
+        self.error_code = error_code
+        self.http_status = http_status
+        self.retry_after = retry_after
+
+    @staticmethod
+    def from_error_code(
+        error_code: str,
+        http_status: int,
+        retry_after: Optional[int] = None,
+    ) -> "VirtualSMSException":
+        message = VirtualSMSException._message_for_code(error_code)
+
+        if error_code in ("BAD_KEY", "BANNED", "PURCHASE_RESTRICTED", "SERVICE_RESTRICTED"):
+            return AuthenticationException(message, error_code, http_status)
+
+        if error_code == "NO_BALANCE":
+            return InsufficientBalanceException(message, error_code, http_status)
+
+        if error_code == "NO_NUMBERS":
+            return NoNumbersException(message, error_code, http_status)
+
+        if error_code in (
+            "WRONG_SERVICE",
+            "WRONG_COUNTRY",
+            "BAD_ACTION",
+            "BAD_STATUS",
+            "NO_PRICES",
+            "INVALID_PROVIDER",
+            "WRONG_EXCEPTION_PHONE",
+            "WRONG_SECURITY",
+        ):
+            return ValidationException(message, error_code, http_status)
+
+        if error_code in (
+            "NO_ACTIVATION",
+            "WRONG_ACTIVATION_ID",
+            "EARLY_CANCEL_DENIED",
+            "RENEW_ACTIVATION_NOT_AVAILABLE",
+            "NEW_ACTIVATION_IMPOSSIBLE",
+            "SIM_OFFLINE",
+        ):
+            return ActivationException(message, error_code, http_status)
+
+        if error_code == "CONCURRENT_LIMIT":
+            return RateLimitException(message, error_code, http_status, retry_after or 0)
+
+        return ServerException(message, error_code, http_status)
+
+    @staticmethod
+    def _message_for_code(error_code: str) -> str:
+        messages = {
+            "BAD_KEY": "Invalid or missing API key.",
+            "BANNED": "Account is banned or IP is blocked.",
+            "PURCHASE_RESTRICTED": "User is restricted from purchasing numbers.",
+            "SERVICE_RESTRICTED": "This service is restricted for your account.",
+            "NO_BALANCE": "Insufficient balance to complete the operation.",
+            "NO_NUMBERS": "No phone numbers available for the requested service and country.",
+            "WRONG_SERVICE": "Invalid or missing service code.",
+            "WRONG_COUNTRY": "Invalid or missing country ID.",
+            "BAD_ACTION": "Invalid or unknown action.",
+            "BAD_STATUS": "Invalid status code provided to setStatus.",
+            "NO_PRICES": "No pricing data available for the requested parameters.",
+            "INVALID_PROVIDER": "The specified pool provider was not found or is disabled.",
+            "WRONG_EXCEPTION_PHONE": "Invalid phone exception parameter.",
+            "WRONG_SECURITY": "Security validation failed.",
+            "NO_ACTIVATION": "Activation not found or does not belong to this account.",
+            "WRONG_ACTIVATION_ID": "Invalid activation ID.",
+            "EARLY_CANCEL_DENIED": "Cannot cancel within the first 5 minutes of activation.",
+            "RENEW_ACTIVATION_NOT_AVAILABLE": "This number is not available for reactivation.",
+            "NEW_ACTIVATION_IMPOSSIBLE": "Cannot create an additional activation on this number.",
+            "SIM_OFFLINE": "The SIM card is currently offline.",
+            "CONCURRENT_LIMIT": "Too many concurrent activations.",
+            "ERROR_SQL": "An internal server error occurred.",
+            "NO_METRICS": "Not enough data available for this service.",
+            "NO_ACTIVATIONS": "No active activations found.",
+        }
+        return messages.get(error_code, "An unexpected error occurred.")
+
+
+class AuthenticationException(VirtualSMSException):
+    pass
+
+
+class InsufficientBalanceException(VirtualSMSException):
+    pass
+
+
+class NoNumbersException(VirtualSMSException):
+    pass
+
+
+class ValidationException(VirtualSMSException):
+    pass
+
+
+class ActivationException(VirtualSMSException):
+    pass
+
+
+class RateLimitException(VirtualSMSException):
+    def __init__(
+        self,
+        message: str,
+        error_code: str,
+        http_status: int,
+        retry_after: int = 0,
+    ):
+        super().__init__(message, error_code, http_status, retry_after=retry_after)
+
+
+class ServerException(VirtualSMSException):
+    pass

virtualsms/parser.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+_ERROR_CODES: List[str] = [
+    "BAD_KEY",
+    "BANNED",
+    "NO_BALANCE",
+    "NO_NUMBERS",
+    "WRONG_SERVICE",
+    "WRONG_COUNTRY",
+    "NO_ACTIVATION",
+    "BAD_ACTION",
+    "BAD_STATUS",
+    "EARLY_CANCEL_DENIED",
+    "WRONG_ACTIVATION_ID",
+    "RENEW_ACTIVATION_NOT_AVAILABLE",
+    "PURCHASE_RESTRICTED",
+    "SERVICE_RESTRICTED",
+    "CONCURRENT_LIMIT",
+    "NO_PRICES",
+    "INVALID_PROVIDER",
+    "ERROR_SQL",
+    "NO_METRICS",
+    "NO_ACTIVATIONS",
+    "NEW_ACTIVATION_IMPOSSIBLE",
+    "SIM_OFFLINE",
+    "WRONG_EXCEPTION_PHONE",
+    "WRONG_SECURITY",
+]
+
+_STATUS_TYPES = ["STATUS_WAIT_CODE", "STATUS_WAIT_RETRY", "STATUS_CANCEL"]
+_SET_STATUS_TYPES = ["ACCESS_READY", "ACCESS_RETRY_GET", "ACCESS_ACTIVATION", "ACCESS_CANCEL"]
+
+
+@dataclass
+class ParsedResponse:
+    is_success: bool = False
+    type: str = ""
+    data: Dict[str, Any] = field(default_factory=dict)
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+
+
+class TextResponseParser:
+    def parse(self, body: str) -> ParsedResponse:
+        body = body.strip()
+
+        if body == "":
+            return ParsedResponse(
+                is_success=False,
+                error_code="UNKNOWN",
+                error_message="Empty response body.",
+            )
+
+        try:
+            decoded = json.loads(body)
+            if isinstance(decoded, (dict, list)):
+                return self._parse_json(decoded, body)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+        if body.startswith("ACCESS_BALANCE:"):
+            balance = float(body[len("ACCESS_BALANCE:") :])
+            return ParsedResponse(
+                is_success=True,
+                type="balance",
+                data={"balance": balance},
+            )
+
+        if body.startswith("ACCESS_NUMBER:"):
+            parts = body.split(":", 2)
+            if len(parts) == 3:
+                return ParsedResponse(
+                    is_success=True,
+                    type="number",
+                    data={
+                        "activation_id": int(parts[1]),
+                        "phone_number": parts[2],
+                    },
+                )
+
+        if body.startswith("STATUS_OK:"):
+            code = body[len("STATUS_OK:") :]
+            return ParsedResponse(
+                is_success=True,
+                type="status",
+                data={
+                    "status": "STATUS_OK",
+                    "code": code if code != "" else None,
+                    "sms_text": None,
+                },
+            )
+
+        if body == "STATUS_OK":
+            return ParsedResponse(
+                is_success=True,
+                type="status",
+                data={"status": "STATUS_OK", "code": None, "sms_text": None},
+            )
+
+        if body.startswith("FULL_SMS:"):
+            sms_text = body[len("FULL_SMS:") :]
+            return ParsedResponse(
+                is_success=True,
+                type="status",
+                data={"status": "FULL_SMS", "code": None, "sms_text": sms_text},
+            )
+
+        for status in _STATUS_TYPES:
+            if body == status:
+                return ParsedResponse(
+                    is_success=True,
+                    type="status",
+                    data={"status": status, "code": None, "sms_text": None},
+                )
+
+        for status in _SET_STATUS_TYPES:
+            if body == status:
+                return ParsedResponse(
+                    is_success=True,
+                    type="set_status",
+                    data={"status": status},
+                )
+
+        error_code = self._detect_error_code(body)
+        if error_code is not None:
+            return ParsedResponse(is_success=False, error_code=error_code)
+
+        return ParsedResponse(
+            is_success=False,
+            error_code="UNKNOWN",
+            error_message=body,
+        )
+
+    def _parse_json(self, decoded: Any, raw: str) -> ParsedResponse:
+        if isinstance(decoded, dict):
+            if decoded.get("status") == "error":
+                error_code = decoded.get("errorCode", "UNKNOWN")
+                error_message = decoded.get("error", "Unknown error.")
+                return ParsedResponse(
+                    is_success=False,
+                    error_code=error_code,
+                    error_message=error_message,
+                )
+
+        return ParsedResponse(
+            is_success=True,
+            type="json",
+            data={"raw": raw, "decoded": decoded},
+        )
+
+    def _detect_error_code(self, body: str) -> Optional[str]:
+        for code in _ERROR_CODES:
+            if body == code:
+                return code
+        return None

virtualsms/response.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class BalanceResponse:
+    balance: float
+
+
+@dataclass
+class NumberResponse:
+    activation_id: int
+    phone_number: str
+
+
+@dataclass
+class StatusResponse:
+    status: str
+    code: Optional[str] = None
+    sms_text: Optional[str] = None

virtualsms/transport.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class Response:
+    status_code: int
+    body: str
+    headers: Dict[str, str] = field(default_factory=dict)
+
+
+class Transport(ABC):
+    @abstractmethod
+    def send(self, url: str, headers: dict) -> Response:
+        ...
+
+
+class UrllibTransport(Transport):
+    def __init__(self, timeout: int = 30):
+        self.timeout = timeout
+
+    def send(self, url: str, headers: dict) -> Response:
+        request = urllib.request.Request(url, method="GET")
+        for key, value in headers.items():
+            request.add_header(key, value)
+
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as resp:
+                body = resp.read().decode("utf-8")
+                status_code = resp.getcode()
+                response_headers = {k: v for k, v in resp.getheaders()}
+                return Response(status_code, body, response_headers)
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8") if e.fp else ""
+            response_headers = {k: v for k, v in e.headers.items()} if e.headers else {}
+            return Response(e.code, body, response_headers)

virtualsmslabs-1.0.0.dist-info/METADATA

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: virtualsmslabs
+Version: 1.0.0
+Summary: Python SDK for the VirtualSMS Consumer API — SMS verification, phone number rental, and activation management.
+Project-URL: Homepage, https://virtualsms.de
+Project-URL: Documentation, https://virtualsms.de/docs/sdk
+Project-URL: Repository, https://github.com/VirtualSMSLabs/python-sdk
+Project-URL: Issues, https://github.com/VirtualSMSLabs/python-sdk/issues
+Author-email: VirtualSMS Labs <contact@virtualsms.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: otp,phone,sms,sms-activate,verification,virtual,virtualsms
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# VirtualSMS Python SDK
+
+Python SDK for the VirtualSMS Consumer API — SMS verification, phone number rental, and activation management.
+
+[![PyPI](https://img.shields.io/pypi/v/virtualsms)](https://pypi.org/project/virtualsms/)
+[![License](https://img.shields.io/github/license/VirtualSMSLabs/python-sdk)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/virtualsms)](https://www.python.org/)
+
+## Requirements
+
+- Python 3.9 or higher
+- No external dependencies (uses standard library only)
+
+## Installation
+
+```bash
+pip install virtualsms
+```
+
+## Quick Start
+
+```python
+from virtualsms import VirtualSMSClient, ActivationStatus
+
+client = VirtualSMSClient("YOUR_API_KEY", "https://api.virtualsms.de")
+
+# Check balance
+balance = client.get_balance()
+print(f"Balance: ${balance.balance:.2f}")
+
+# Order a WhatsApp number in Brazil
+number = client.get_number("wa", 73, max_price=2.00)
+print(f"Number: {number.phone_number} (ID: {number.activation_id})")
+
+# Set status to ready (SMS sent)
+client.set_status(number.activation_id, ActivationStatus.READY)
+
+# Poll for SMS code
+status = client.get_status(number.activation_id)
+if status.code is not None:
+    print(f"SMS code: {status.code}")
+    # Complete the activation
+    client.set_status(number.activation_id, ActivationStatus.COMPLETE)
+```
+
+## API Reference
+
+### Client Constructor
+
+```python
+client = VirtualSMSClient(
+    api_key="YOUR_API_KEY",           # Your API key (required)
+    base_url="https://api.virtualsms.de",  # API base URL (optional)
+    transport=None,                    # Optional custom transport
+)
+```
+
+### Methods
+
+#### Account
+
+##### `get_balance() -> BalanceResponse`
+
+Returns the current account balance.
+
+```python
+balance = client.get_balance()
+print(balance.balance)  # 10.50
+```
+
+#### Information & Pricing
+
+##### `get_countries(pool_provider=None) -> dict`
+
+Returns all available countries.
+
+##### `get_services_list(country=None, lang=None) -> dict`
+
+Returns available services for a country.
+
+##### `get_operators(country, pool_provider=None) -> list`
+
+Returns available mobile operators for a country.
+
+##### `get_prices(service=None, country=None, pool_provider=None) -> dict`
+
+Returns pricing data organized by country and service.
+
+##### `get_prices_extended(service=None, country=None, free_price=None, pool_provider=None) -> dict`
+
+Returns extended pricing with price tiers.
+
+##### `get_prices_verification(service=None, pool_provider=None) -> dict`
+
+Returns pricing in inverted format (service → country).
+
+##### `get_numbers_status(country, operator=None, pool_provider=None) -> dict`
+
+Returns available phone quantity per service.
+
+##### `get_top_countries_by_service(service) -> list`
+
+Returns top 10 countries for a service, ranked by purchase share and success rate.
+
+#### Ordering Numbers
+
+##### `get_number(service, country, **options) -> NumberResponse`
+
+Orders a phone number. Returns text format response.
+
+```python
+number = client.get_number(
+    service="wa",
+    country=73,
+    max_price=2.00,
+    operator="claro",
+    forward=True,
+)
+print(number.activation_id)   # 123
+print(number.phone_number)    # 447777777777
+```
+
+**Options:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `max_price` | `float` | Maximum price willing to pay |
+| `operator` | `str` | Mobile operator filter |
+| `phone_exception` | `str` | Phone prefixes to exclude (comma-separated) |
+| `forward` | `bool` | Enable call forwarding |
+| `activation_type` | `int` | Activation type: 0=SMS, 1=number, 2=voice |
+| `language` | `str` | Language for voice activation |
+| `use_cashback` | `bool` | Use cashback balance first |
+| `user_id` | `str` | End-user ID for tracking |
+| `ref` | `str` | Referral ID |
+| `pool_provider` | `str` | Pool provider: alpha, prime, gamma, zeta |
+
+##### `get_number_v2(service, country, **options) -> dict`
+
+Same as `get_number` but returns JSON with additional fields. Supports `order_id` for idempotency.
+
+#### Activation Management
+
+##### `set_status(id, status) -> str`
+
+Changes activation status.
+
+```python
+from virtualsms import ActivationStatus
+
+client.set_status(activation_id, ActivationStatus.READY)     # 1 - SMS sent
+client.set_status(activation_id, ActivationStatus.RETRY)     # 3 - Request another SMS
+client.set_status(activation_id, ActivationStatus.COMPLETE)  # 6 - Finish
+client.set_status(activation_id, ActivationStatus.CANCEL)    # 8 - Cancel
+```
+
+##### `get_status(id) -> StatusResponse`
+
+Returns activation status in text format.
+
+```python
+status = client.get_status(activation_id)
+print(status.status)   # STATUS_OK, STATUS_WAIT_CODE, STATUS_CANCEL
+print(status.code)     # 123456 (None if not yet received)
+```
+
+##### `get_status_v2(id) -> dict`
+
+Returns activation status in JSON format with SMS/call details.
+
+##### `get_active_activations() -> list`
+
+Returns all currently active activations.
+
+##### `check_extra_activation(id) -> dict`
+
+Checks if a number is available for reactivation.
+
+##### `get_extra_activation(id) -> NumberResponse`
+
+Creates an extra activation on a previously used number.
+
+#### Notifications
+
+##### `get_notifications() -> dict`
+
+Returns user notifications including penalties, low balance alerts, and admin messages.
+
+### Constants
+
+#### ActivationStatus
+
+```python
+ActivationStatus.READY     # 1 - SMS has been sent to the number
+ActivationStatus.RETRY     # 3 - Request another SMS code
+ActivationStatus.COMPLETE  # 6 - Finish activation
+ActivationStatus.CANCEL    # 8 - Cancel activation
+```
+
+#### PoolProvider
+
+```python
+PoolProvider.ALPHA  # 'alpha'
+PoolProvider.PRIME  # 'prime'
+PoolProvider.GAMMA  # 'gamma'
+PoolProvider.ZETA   # 'zeta'
+```
+
+## Error Handling
+
+The SDK raises typed exceptions for all API errors. Each error code maps to a specific exception class:
+
+```python
+from virtualsms import (
+    VirtualSMSClient,
+    VirtualSMSException,
+    AuthenticationException,
+    InsufficientBalanceException,
+    NoNumbersException,
+    ValidationException,
+    ActivationException,
+    RateLimitException,
+    ServerException,
+)
+
+try:
+    number = client.get_number("wa", 73)
+except AuthenticationException:
+    # BAD_KEY, BANNED, PURCHASE_RESTRICTED, SERVICE_RESTRICTED
+    pass
+except InsufficientBalanceException:
+    # NO_BALANCE
+    pass
+except NoNumbersException:
+    # NO_NUMBERS
+    pass
+except ValidationException:
+    # WRONG_SERVICE, WRONG_COUNTRY, BAD_ACTION, BAD_STATUS, NO_PRICES, INVALID_PROVIDER
+    pass
+except ActivationException:
+    # NO_ACTIVATION, WRONG_ACTIVATION_ID, EARLY_CANCEL_DENIED, RENEW_ACTIVATION_NOT_AVAILABLE
+    pass
+except RateLimitException as e:
+    # CONCURRENT_LIMIT — check e.retry_after
+    pass
+except ServerException:
+    # ERROR_SQL, unknown errors
+    pass
+```
+
+### Error Code Reference
+
+| Error Code | Exception | Description |
+|-----------|-----------|-------------|
+| `BAD_KEY` | `AuthenticationException` | Invalid API key |
+| `BANNED` | `AuthenticationException` | Account banned or IP blocked |
+| `PURCHASE_RESTRICTED` | `AuthenticationException` | User restricted from purchasing |
+| `SERVICE_RESTRICTED` | `AuthenticationException` | Service restricted for account |
+| `NO_BALANCE` | `InsufficientBalanceException` | Insufficient balance |
+| `NO_NUMBERS` | `NoNumbersException` | No numbers available |
+| `WRONG_SERVICE` | `ValidationException` | Invalid service code |
+| `WRONG_COUNTRY` | `ValidationException` | Invalid country ID |
+| `BAD_ACTION` | `ValidationException` | Invalid action |
+| `BAD_STATUS` | `ValidationException` | Invalid status code |
+| `NO_PRICES` | `ValidationException` | No pricing data available |
+| `INVALID_PROVIDER` | `ValidationException` | Invalid pool provider |
+| `NO_ACTIVATION` | `ActivationException` | Activation not found |
+| `WRONG_ACTIVATION_ID` | `ActivationException` | Invalid activation ID |
+| `EARLY_CANCEL_DENIED` | `ActivationException` | Cannot cancel within 5 minutes |
+| `RENEW_ACTIVATION_NOT_AVAILABLE` | `ActivationException` | Number not available for reactivation |
+| `CONCURRENT_LIMIT` | `RateLimitException` | Too many concurrent activations |
+| `ERROR_SQL` | `ServerException` | Internal server error |
+
+## Tracking Headers
+
+The SDK sends anonymous tracking headers with every request for analytics and debugging:
+
+| Header | Value | Privacy |
+|--------|-------|---------|
+| `X-SDK-Version` | `1.0.0` | SDK version string |
+| `X-SDK-Language` | `python` | SDK language |
+| `X-SDK-Machine-Id` | SHA-256 hash of `platform.platform()` + `sys.implementation.name` (truncated to 32 chars) | Irreversible hash — no hostname or IP exposed |
+| `X-SDK-Timestamp` | ISO 8601 UTC timestamp | Request time |
+
+No personally identifiable information is transmitted. The machine ID is a one-way hash and cannot be reversed to identify the source machine.
+
+## Custom Transport
+
+By default, the SDK uses `urllib.request` for HTTP requests. You can provide your own transport implementation:
+
+```python
+from virtualsms import VirtualSMSClient, Transport, Response
+
+class MyTransport(Transport):
+    def send(self, url: str, headers: dict) -> Response:
+        # Your HTTP implementation
+        return Response(status_code=200, body="ACCESS_BALANCE:10.50")
+
+client = VirtualSMSClient("API_KEY", "https://api.example.com", transport=MyTransport())
+```
+
+## Examples
+
+See the `examples/` directory:
+
+- [`balance.py`](examples/balance.py) — Check account balance
+- [`order_number.py`](examples/order_number.py) — Order a phone number
+- [`full_workflow.py`](examples/full_workflow.py) — Complete SMS verification workflow
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- [PyPI](https://pypi.org/project/virtualsms/)
+- [GitHub](https://github.com/VirtualSMSLabs/python-sdk)
+- [API Documentation](https://virtualsms.de/docs)
+- [MCP Integration](https://virtualsms.de/docs/mcp)

virtualsmslabs-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+virtualsms/__init__.py,sha256=tpdXEuFgdolHHxQ4Kp8PJsLMcSvS73fAbJK4kdHgjJo,935
+virtualsms/client.py,sha256=FKlMvuKc-uWVFXXzVPhKhY_wj1Ka2HQ5KuVZ3eFXHU0,11209
+virtualsms/constants.py,sha256=dtpxUVPPd3cJ8Ml3SGRkvPwrGsWpm0W-ILulGuJf-bQ,221
+virtualsms/exceptions.py,sha256=W5evMaR-vyjd59CE93XuofzIy5IJ9NFD0-aViK1qN5g,4525
+virtualsms/parser.py,sha256=a0z50BbgKfRWGceBHP0gIvqET0AVSVkpfAJINpzPiOU,4802
+virtualsms/response.py,sha256=G6UV5lj6lvrA2lXj0VuVH5Ngr2XZUeSO9mEUMGymHb8,350
+virtualsms/transport.py,sha256=fuX61xh5HUF1FWixXWRYdaQUwxVehUm6fUFBfbmm9nk,1322
+virtualsmslabs-1.0.0.dist-info/METADATA,sha256=RKvmLV1TwWwiBsyo4_pViNYkX8ejeb1F3YhVVzP-kZQ,11053
+virtualsmslabs-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+virtualsmslabs-1.0.0.dist-info/licenses/LICENSE,sha256=TiJ43kHbayLnloMYbsfwBE-dnVUuta3a6mhbzsXo6Y4,1072
+virtualsmslabs-1.0.0.dist-info/RECORD,,

virtualsmslabs-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

virtualsmslabs-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VirtualSMS Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.