smsman-client 0.2.0__py3-none-any.whl

sms_man/__init__.py

@@ -0,0 +1,12 @@
+from sms_man.client import DEFAULT_REF, SmsMan
+from sms_man.errors import SmsManError
+from sms_man.types import HandlerStatusResult, PhoneNumberOrder, SmsCodeResult
+
+__all__ = [
+    "DEFAULT_REF",
+    "SmsMan",
+    "SmsManError",
+    "HandlerStatusResult",
+    "PhoneNumberOrder",
+    "SmsCodeResult",
+]

sms_man/client.py

@@ -0,0 +1,349 @@
+from typing import Any
+
+import httpx
+
+from sms_man.errors import SmsManError
+from sms_man.types import HandlerStatusResult, PhoneNumberOrder, SmsCodeResult
+
+DEFAULT_REF = "s_iNhkmN48Jf"
+
+
+class SmsMan:
+    """Client for the SMS-MAN virtual number and SMS activation API.
+
+    Args:
+        token: User API token for SMS-MAN.
+        base_url: Base URL for SMS-MAN API. Defaults to "https://api.sms-man.com".
+        timeout: HTTP request timeout in seconds. Defaults to 30.0.
+
+    Examples:
+        >>> from sms_man import SmsMan
+        >>> client = SmsMan(token="your_api_token")
+        >>> balance = client.get_balance()
+    """
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str = "https://api.sms-man.com",
+        timeout: float = 30.0,
+    ) -> None:
+        if not token:
+            raise SmsManError("API token is required")
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(base_url=self.base_url, timeout=self.timeout)
+
+    def close(self) -> None:
+        """Closes the underlying HTTP client session."""
+        self._client.close()
+
+    def __enter__(self) -> "SmsMan":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def get_balance(self) -> float:
+        """Retrieves user account balance.
+
+        Returns:
+            Current balance as a float.
+
+        Examples:
+            >>> balance = client.get_balance()
+            >>> print(balance)
+            120.0
+        """
+        data = self._call_control("get-balance")
+        bal = data.get("balance")
+        if bal is None:
+            raise SmsManError("Missing balance in API response", response_data=data)
+        try:
+            return float(bal)
+        except (ValueError, TypeError) as exc:
+            raise SmsManError(f"Invalid balance format: {bal}", response_data=data) from exc
+
+    def get_limits(
+        self,
+        country_id: int | None = None,
+        application_id: int | None = None,
+    ) -> Any:
+        """Retrieves available number limits and counts.
+
+        Args:
+            country_id: Optional country identifier.
+            application_id: Optional service identifier.
+
+        Returns:
+            Limits response dictionary.
+
+        Examples:
+            >>> limits = client.get_limits(country_id=1, application_id=1)
+        """
+        params: dict[str, Any] = {}
+        if country_id is not None:
+            params["country_id"] = country_id
+        if application_id is not None:
+            params["application_id"] = application_id
+        return self._call_control("limits", params)
+
+    def get_prices(self, country_id: int | None = None) -> Any:
+        """Retrieves service pricing catalog.
+
+        Args:
+            country_id: Optional country identifier.
+
+        Returns:
+            Pricing dictionary.
+
+        Examples:
+            >>> prices = client.get_prices(country_id=1)
+        """
+        params: dict[str, Any] = {}
+        if country_id is not None:
+            params["country_id"] = country_id
+        return self._call_control("get-prices", params)
+
+    def get_countries(self) -> Any:
+        """Retrieves list of supported countries.
+
+        Returns:
+            Countries dictionary.
+
+        Examples:
+            >>> countries = client.get_countries()
+        """
+        return self._call_control("countries")
+
+    def get_applications(self) -> Any:
+        """Retrieves list of supported applications and services.
+
+        Returns:
+            Applications dictionary.
+
+        Examples:
+            >>> apps = client.get_applications()
+        """
+        return self._call_control("applications")
+
+    def get_number(self, country_id: int, application_id: int) -> PhoneNumberOrder:
+        """Orders a disposable virtual phone number.
+
+        Args:
+            country_id: Country identifier (or 0 for random).
+            application_id: Service identifier.
+
+        Returns:
+            PhoneNumberOrder with requestId and number string.
+
+        Examples:
+            >>> order = client.get_number(country_id=1, application_id=1)
+            >>> print(order.number)
+        """
+        data = self._call_control(
+            "get-number",
+            {
+                "country_id": country_id,
+                "application_id": application_id,
+                "ref": DEFAULT_REF,
+            },
+        )
+        req_id = data.get("request_id")
+        number = data.get("number_p") or data.get("number")
+        if not req_id or not number:
+            raise SmsManError("Incomplete number data returned by API", response_data=data)
+        return PhoneNumberOrder(request_id=int(req_id), number=str(number))
+
+    def get_sms(self, request_id: int) -> SmsCodeResult:
+        """Retrieves the received SMS code for an active order.
+
+        Args:
+            request_id: Order request ID.
+
+        Returns:
+            SmsCodeResult object.
+
+        Examples:
+            >>> res = client.get_sms(12345)
+            >>> print(res.sms_code)
+        """
+        data = self._call_control("get-sms", {"request_id": request_id})
+        return SmsCodeResult(
+            sms_code=data.get("sms_code"),
+            error=data.get("error_msg"),
+        )
+
+    def set_status(self, request_id: int, status: str) -> bool:
+        """Sets status of an active number order (e.g. 'ready', 'reject').
+
+        Args:
+            request_id: Order request ID.
+            status: Target status string.
+
+        Returns:
+            True if status updated.
+
+        Examples:
+            >>> client.set_status(12345, "reject")
+        """
+        self._call_control("set-status", {"request_id": request_id, "status": status})
+        return True
+
+    def handler_get_balance(self) -> float:
+        """Retrieves account balance via SMS-Activate compatible handler endpoint.
+
+        Returns:
+            Account balance.
+
+        Examples:
+            >>> balance = client.handler_get_balance()
+        """
+        text = self._call_handler("getBalance")
+        if not text.startswith("ACCESS_BALANCE:"):
+            raise SmsManError(f"Unexpected balance response: {text}", code=text)
+        try:
+            return float(text[len("ACCESS_BALANCE:") :])
+        except ValueError as exc:
+            raise SmsManError(f"Invalid balance format: {text}", code=text) from exc
+
+    def handler_get_number(
+        self,
+        country: int | str,
+        service: str,
+    ) -> PhoneNumberOrder:
+        """Orders a number via the handler endpoint.
+
+        Args:
+            country: Country identifier.
+            service: Service code (e.g. 'tg', 'vk').
+
+        Returns:
+            PhoneNumberOrder with request ID and phone number.
+
+        Examples:
+            >>> order = client.handler_get_number(1, "tg")
+        """
+        text = self._call_handler(
+            "getNumber",
+            {
+                "country": country,
+                "service": service,
+                "ref": DEFAULT_REF,
+            },
+        )
+        if not text.startswith("ACCESS_NUMBER:"):
+            raise SmsManError(f"Failed to order number: {text}", code=text)
+        parts = text.split(":")
+        if len(parts) < 3:
+            raise SmsManError(f"Malformed ACCESS_NUMBER response: {text}", code=text)
+        return PhoneNumberOrder(request_id=int(parts[1]), number=parts[2])
+
+    def handler_get_status(self, order_id: int | str) -> HandlerStatusResult:
+        """Checks status and verification code via the handler endpoint.
+
+        Args:
+            order_id: Order ID.
+
+        Returns:
+            HandlerStatusResult object.
+
+        Examples:
+            >>> status = client.handler_get_status(12345)
+        """
+        text = self._call_handler("getStatus", {"id": order_id})
+        if text.startswith("STATUS_OK:"):
+            return HandlerStatusResult(status="STATUS_OK", code=text[len("STATUS_OK:") :])
+        return HandlerStatusResult(status=text)
+
+    def handler_set_status(self, order_id: int | str, status: int) -> str:
+        """Sets status via the handler endpoint.
+
+        Args:
+            order_id: Order ID.
+            status: Status code.
+
+        Returns:
+            Status text.
+
+        Examples:
+            >>> client.handler_set_status(12345, 1)
+        """
+        return self._call_handler("setStatus", {"id": order_id, "status": status})
+
+    def handler_get_prices(self, country: int | str | None = None) -> Any:
+        """Retrieves price catalog via the handler endpoint.
+
+        Args:
+            country: Optional country ID.
+
+        Returns:
+            Prices dictionary or response text.
+
+        Examples:
+            >>> prices = client.handler_get_prices(1)
+        """
+        params: dict[str, Any] = {}
+        if country is not None:
+            params["country"] = country
+        text = self._call_handler("getPrices", params)
+        import json
+
+        try:
+            return json.loads(text)
+        except Exception:
+            return text
+
+    def _call_control(self, endpoint: str, params: dict[str, Any] | None = None) -> Any:
+        query: dict[str, Any] = {"token": self.token}
+        if params:
+            query.update(params)
+
+        try:
+            resp = self._client.get(f"/control/{endpoint}", params=query)
+        except httpx.RequestError as exc:
+            raise SmsManError(f"HTTP request error: {exc}") from exc
+
+        try:
+            data = resp.json()
+        except Exception as exc:
+            raise SmsManError(f"Invalid JSON: {resp.text}") from exc
+
+        if isinstance(data, dict) and data.get("success") is False:
+            code = data.get("error_code")
+            msg = data.get("error_msg") or f"SMS-MAN error: {code}"
+            raise SmsManError(msg, code=code, response_data=data)
+        return data
+
+    def _call_handler(self, action: str, params: dict[str, Any] | None = None) -> str:
+        query: dict[str, Any] = {
+            "action": action,
+            "api_key": self.token,
+        }
+        if params:
+            query.update(params)
+
+        try:
+            resp = self._client.get("/stubs/handler_api.php", params=query)
+        except httpx.RequestError as exc:
+            raise SmsManError(f"HTTP request error: {exc}") from exc
+
+        text = resp.text.strip()
+        error_codes = {
+            "BAD_KEY",
+            "NO_KEY",
+            "ERROR_SQL",
+            "BAD_ACTION",
+            "BAD_SERVICE",
+            "NO_ACTIVATION",
+            "BAD_STATUS",
+            "NO_BALANCE",
+            "NO_NUMBERS",
+            "WRONG_SERVICE",
+        }
+        for err in error_codes:
+            if text == err or text.startswith(f"{err}:"):
+                raise SmsManError(f"API error: {text}", code=text)
+
+        return text

sms_man/errors.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+
+class SmsManError(Exception):
+    """Exception raised by the SMS-MAN API client.
+
+    Attributes:
+        code: Error code string (e.g. wrong_token, no_numbers, BAD_KEY).
+        response_data: Raw response payload.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        response_data: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.response_data = response_data

sms_man/types.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class PhoneNumberOrder:
+    """Ordered virtual phone number details.
+
+    Attributes:
+        request_id: Order request ID.
+        number: Assigned phone number string.
+    """
+
+    request_id: int
+    number: str
+
+
+@dataclass
+class SmsCodeResult:
+    """SMS verification code result.
+
+    Attributes:
+        sms_code: Verification code if received.
+        error: Error message string if code not yet arrived.
+    """
+
+    sms_code: str | None = None
+    error: str | None = None
+
+
+@dataclass
+class HandlerStatusResult:
+    """Compatible handler status response.
+
+    Attributes:
+        status: Status code string (e.g. STATUS_OK, STATUS_WAIT_CODE).
+        code: Verification code if status is STATUS_OK.
+    """
+
+    status: str
+    code: str | None = None

smsman_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: smsman-client
+Version: 0.2.0
+Summary: Python client for the SMS-MAN virtual number and SMS activation API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://sms-man.com/site/api
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# smsman-client
+
+[![PyPI version](https://img.shields.io/pypi/v/smsman-client.svg)](https://pypi.org/project/smsman-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/pypi/pyversions/smsman-client.svg)](https://pypi.org/project/smsman-client/)
+
+Modern, fully typed Python client library for the [SMS-MAN](https://sms-man.com/site/api) virtual phone numbers and SMS verification API.
+
+Official API documentation: <https://sms-man.com/site/api>
+
+---
+
+## Features
+
+- 📱 **Dual Protocol Support** — Support for both the native SMS-MAN Control API (`/control/`) and the SMS-Activate compatible handler protocol (`/stubs/handler_api.php`).
+- 🌍 **Global Coverage** — Rent disposable virtual phone numbers across 300+ countries and hundreds of applications.
+- 🐍 **Modern Pythonic Design** — Type annotations, dataclass models (`PhoneNumberOrder`, `SmsCodeResult`), context manager support (`with SmsMan(...) as client:`), and custom exceptions.
+- 🔄 **Full Activation Lifecycle** — Rent numbers, check status, fetch SMS codes, or reject/cancel.
+
+---
+
+## Installation
+
+```bash
+pip install smsman-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects your account balance. It does not order numbers or consume funds:
+
+```python
+import os
+from sms_man import SmsMan
+
+with SmsMan(api_key=os.environ["SMSMAN_API_KEY"]) as client:
+    balance = client.get_balance()
+    print(f"Current SMS-MAN balance: ${balance:.2f} USD")
+```
+
+---
+
+## Usage Guide
+
+### 1. Renting a Number and Receiving an SMS Code (Control API)
+
+Full activation lifecycle using the native Control API:
+
+```python
+import time
+from sms_man import SmsMan, SmsManError
+
+with SmsMan(api_key="your_api_key") as client:
+    # 1. Order a number for Telegram (app 1) in USA (country 1)
+    order = client.get_number(country_id=1, application_id=1)
+    print(f"Received number: +{order.number} (Request ID: {order.request_id})")
+
+    # 2. Poll for the incoming SMS verification code
+    code = None
+    for _ in range(30):
+        time.sleep(3)
+        try:
+            res = client.get_sms(order.request_id)
+            if res.sms_code:
+                code = res.sms_code
+                break
+        except SmsManError as err:
+            if err.code == "wait_code":
+                continue
+            raise err
+
+    if code:
+        print(f"Verification code received: {code}")
+    else:
+        print("Timeout reached. Rejecting number to refund balance...")
+        client.set_status(order.request_id, "reject")
+```
+
+### 2. Inspecting Limits, Prices & Applications
+
+Check available limits and application IDs before ordering:
+
+```python
+countries = client.get_countries()
+print("Countries:", countries)
+
+apps = client.get_applications()
+print("Applications:", apps)
+
+limits = client.get_limits(country_id=1, application_id=1)
+print("Available limits:", limits)
+```
+
+### 3. Using the SMS-Activate Protocol (`handler_api.php`)
+
+If your existing workflow uses standard `handler_api.php`:
+
+```python
+# 1. Check balance via handler
+balance = client.handler_get_balance()
+print(f"Handler balance: {balance}")
+
+# 2. Order number via handler
+activation = client.handler_get_number(service="tg", country=1)
+print(f"Order ID: {activation.id}, Number: {activation.number}")
+
+# 3. Mark ready (status 1)
+client.handler_set_status(activation.id, 1)
+
+# 4. Check status
+status = client.handler_get_status(activation.id)
+print(f"Status: {status.status}, Code: {status.code}")
+
+# 5. Complete activation (status 6) or cancel (status 8)
+client.handler_set_status(activation.id, 6)
+```
+
+---
+
+## API Reference
+
+### `SmsMan` Class
+
+#### Constructor
+
+```python
+SmsMan(
+    api_key: str,
+    base_url: str = "https://api.sms-man.com",
+    timeout: float = 30.0,
+)
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_key` | `str` | **Required** | Your SMS-MAN API key. |
+| `base_url` | `str` | `"https://api.sms-man.com"` | Base URL of SMS-MAN API. |
+| `timeout` | `float` | `30.0` | Request timeout in seconds. |
+
+#### Control API Methods (`/control/`)
+
+- **`get_balance() -> float`** — Returns current balance in USD.
+- **`get_limits(country_id=None, application_id=None) -> Any`** — Checks number availability and limits.
+- **`get_prices(country_id=None) -> Any`** — Returns pricing for services and countries.
+- **`get_countries() -> Any`** — Lists all supported countries with IDs.
+- **`get_applications() -> Any`** — Lists all supported applications with IDs.
+- **`get_number(country_id: int, application_id: int) -> PhoneNumberOrder`** — Orders a number for the application.
+- **`get_sms(request_id: int) -> SmsCodeResult`** — Checks for received SMS verification code.
+- **`set_status(request_id: int, status: str) -> bool`** — Sets status (`'ready'` or `'reject'`).
+
+#### Handler API Methods (`/stubs/handler_api.php`)
+
+- **`handler_get_balance() -> float`** — Returns balance via handler API.
+- **`handler_get_number(service, country=None) -> HandlerNumberResult`** — Orders number (`ACCESS_NUMBER`).
+- **`handler_get_status(order_id: int | str) -> HandlerStatusResult`** — Retrieves status and code.
+- **`handler_set_status(order_id: int | str, status: int) -> str`** — Updates activation state (1 = ready, 6 = complete, 8 = cancel).
+- **`handler_get_prices(country=None) -> Any`** — Retrieves prices via handler API.
+
+---
+
+## Error Handling
+
+When an API error occurs, `SmsManError` is raised:
+
+```python
+from sms_man import SmsMan, SmsManError
+
+try:
+    with SmsMan(api_key="invalid_key") as client:
+        client.get_balance()
+except SmsManError as exc:
+    print(f"SMS-MAN Error: {exc.message} (Code: {exc.code})")
+```
+
+Common error codes:
+- `no_numbers` — No available phone numbers for selected application/country.
+- `balance_empty` — Insufficient funds on account.
+- `wrong_token` — Invalid API key.
+- `wait_code` — SMS code has not arrived yet.
+- `WRONG_ACTIVATION_ID` — Order ID does not exist or expired.
+
+---
+
+## License
+
+ISC

smsman_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sms_man/__init__.py,sha256=_lvCfh5od0lIgzhoug-pelEwrMupkv9einDpnogIu5g,304
+sms_man/client.py,sha256=B-idPCShumSh18YWzZ9AS1lKrmh9PiuEEcEuuvZ10aI,10814
+sms_man/errors.py,sha256=WCoBTu6NzWL-SXHlKrgDgQT0O4KuCwfGRM66QtH-v1Q,489
+sms_man/types.py,sha256=3fQYrLBqrzWzVVO3_7nC7EAGZwNDhZT9g3uP2WvCHlc,810
+smsman_client-0.2.0.dist-info/METADATA,sha256=IN3ASgK8DYrgJFHlRh5iRvk8yBr9TG8Nt4C_FllKucc,6488
+smsman_client-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+smsman_client-0.2.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+smsman_client-0.2.0.dist-info/RECORD,,

smsman_client-0.2.0.dist-info/WHEEL

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

smsman_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.