vaksms-client 0.2.0__py3-none-any.whl

vak_sms/__init__.py

@@ -0,0 +1,14 @@
+"""VAK-SMS Python Client."""
+
+from .client import DEFAULT_SOFT_ID, VakSmsClient
+from .errors import VakSmsError
+from .types import CountNumber, CountryOperator, VakNumber
+
+__all__ = [
+    "DEFAULT_SOFT_ID",
+    "CountNumber",
+    "CountryOperator",
+    "VakNumber",
+    "VakSmsClient",
+    "VakSmsError",
+]

vak_sms/client.py

@@ -0,0 +1,365 @@
+"""VAK-SMS API client implementation."""
+
+import time
+from typing import Any
+
+import httpx
+
+from .errors import ERROR_DESCRIPTIONS, VakSmsError
+from .types import CountNumber, CountryOperator, VakNumber
+
+DEFAULT_SOFT_ID = ""
+DEFAULT_BASE_URL = "https://vak-sms.com"
+
+
+class VakSmsClient:
+    """Client for the VAK-SMS temporary number and SMS OTP reception service.
+
+    Args:
+        api_key: VAK-SMS API key.
+        base_url: Base URL of the API. Defaults to https://vak-sms.com.
+        timeout: HTTP request timeout in seconds. Defaults to 30.0.
+        soft_id: Optional software/partner identifier.
+
+    Examples:
+        >>> from vak_sms import VakSmsClient
+        >>> client = VakSmsClient(api_key="your_api_key")
+        >>> balance = client.get_balance()
+        >>> print(balance)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        soft_id: str | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise VakSmsError("api_key is required to initialize VakSmsClient", "apiKeyNotFound")
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.soft_id = soft_id if soft_id is not None else DEFAULT_SOFT_ID
+        self._client = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    def __enter__(self) -> "VakSmsClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Closes the underlying HTTP client session."""
+        self._client.close()
+
+    def get_balance(self) -> float:
+        """Retrieves the current account balance in RUB.
+
+        Returns:
+            The account balance as a float.
+
+        Raises:
+            VakSmsError: If the server returns an error or unexpected response.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> balance = client.get_balance()
+            >>> print(f"Balance: {balance} RUB")
+        """
+        data = self._request("/api/getBalance/")
+        if (
+            isinstance(data, dict)
+            and "balance" in data
+            and isinstance(data["balance"], (int, float))
+        ):
+            return float(data["balance"])
+        raise VakSmsError("Invalid getBalance response", "INVALID_RESPONSE", data)
+
+    def get_number(
+        self,
+        service: str | list[str],
+        country: str | None = None,
+        operator: str | None = None,
+        rent: bool = False,
+        soft_id: str | None = None,
+    ) -> VakNumber:
+        """Orders a temporary virtual phone number.
+
+        Args:
+            service: Service code (e.g. 'tg', 'wa') or list of codes.
+            country: 2-letter country code (e.g. 'ru', 'kz').
+            operator: Optional network operator name (e.g. 'megafon').
+            rent: Whether to lease number under extended rental.
+            soft_id: Optional software/partner identifier.
+
+        Returns:
+            VakNumber containing phone number and idNum.
+
+        Raises:
+            VakSmsError: If the number cannot be ordered or stock is exhausted.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> number = client.get_number("tg", country="ru")
+            >>> print(number.tel, number.id_num)
+        """
+        srv = ",".join(service) if isinstance(service, list) else service
+        params: dict[str, Any] = {"service": srv}
+
+        if country:
+            params["country"] = country
+        if operator:
+            params["operator"] = operator
+        if rent:
+            params["rent"] = "true"
+
+        effective_soft_id = soft_id if soft_id is not None else self.soft_id
+        if effective_soft_id:
+            params["softId"] = effective_soft_id
+
+        data = self._request("/api/getNumber/", params)
+        if isinstance(data, dict) and "idNum" in data and "tel" in data:
+            return VakNumber(
+                id_num=str(data["idNum"]),
+                tel=str(data["tel"]),
+                service=srv,
+                rent=rent,
+            )
+        raise VakSmsError("Invalid getNumber response", "INVALID_RESPONSE", data)
+
+    def prolong_number(
+        self,
+        service: str,
+        tel: str | int,
+        soft_id: str | None = None,
+    ) -> VakNumber:
+        """Extends rental duration for an existing phone number.
+
+        Args:
+            service: Service code.
+            tel: Phone number without plus sign.
+            soft_id: Optional software/partner identifier.
+
+        Returns:
+            VakNumber with extended order details.
+
+        Raises:
+            VakSmsError: If extension request fails.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> order = client.prolong_number("tg", "79991234567")
+            >>> print(order.id_num)
+        """
+        params: dict[str, Any] = {"service": service, "tel": str(tel)}
+        effective_soft_id = soft_id if soft_id is not None else self.soft_id
+        if effective_soft_id:
+            params["softId"] = effective_soft_id
+
+        data = self._request("/api/prolongNumber/", params)
+        if isinstance(data, dict) and "idNum" in data and "tel" in data:
+            return VakNumber(
+                id_num=str(data["idNum"]),
+                tel=str(data["tel"]),
+                service=service,
+            )
+        raise VakSmsError("Invalid prolongNumber response", "INVALID_RESPONSE", data)
+
+    def get_sms_code(
+        self,
+        id_num: str,
+        all_codes: bool = False,
+    ) -> str | list[str] | None:
+        """Retrieves incoming SMS code(s) for an active order.
+
+        Args:
+            id_num: Activation identifier.
+            all_codes: Whether to return all received SMS codes.
+
+        Returns:
+            Single code string, list of strings, or None if code is not yet received.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> code = client.get_sms_code("abcd1234ef")
+            >>> print("Received SMS code:", code)
+        """
+        params: dict[str, Any] = {"idNum": id_num}
+        if all_codes:
+            params["all"] = "true"
+
+        data = self._request("/api/getSmsCode/", params)
+        if isinstance(data, dict) and "smsCode" in data:
+            return data["smsCode"]
+        return None
+
+    def wait_for_code(
+        self,
+        id_num: str,
+        timeout: float = 120.0,
+        interval: float = 3.0,
+    ) -> str | None:
+        """Polls until an SMS code arrives or timeout expires.
+
+        Args:
+            id_num: Activation identifier.
+            timeout: Maximum seconds to wait. Defaults to 120.0.
+            interval: Polling frequency in seconds. Defaults to 3.0.
+
+        Returns:
+            Received SMS code string or None if timed out.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> code = client.wait_for_code("abcd1234ef", timeout=60.0)
+            >>> print("SMS code:", code)
+        """
+        start = time.time()
+        while time.time() - start < timeout:
+            code = self.get_sms_code(id_num)
+            if code:
+                if isinstance(code, list):
+                    return code[-1] if code else None
+                return str(code)
+            time.sleep(interval)
+        return None
+
+    def set_status(self, id_num: str, status: str) -> str:
+        """Updates the status of an ongoing number activation.
+
+        Status options:
+            - 'send': Wait for another SMS code
+            - 'end': Successfully finish activation
+            - 'bad': Report number as defective/cancel
+
+        Args:
+            id_num: Activation identifier.
+            status: Status command ('send', 'end', 'bad').
+
+        Returns:
+            Status confirmation string.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> client.set_status("abcd1234ef", "end")
+            'update'
+        """
+        data = self._request("/api/setStatus/", {"idNum": id_num, "status": status})
+        if isinstance(data, dict) and "status" in data:
+            return str(data["status"])
+        return "ok"
+
+    def get_count_number(
+        self,
+        service: str,
+        country: str = "ru",
+        operator: str | None = None,
+    ) -> CountNumber:
+        """Queries available number count and unit price for a service.
+
+        Args:
+            service: Service code.
+            country: Country code (default 'ru').
+            operator: Optional network operator name.
+
+        Returns:
+            CountNumber object with stock and price.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> count = client.get_count_number("tg", "ru")
+            >>> print(count.count, count.price)
+        """
+        params: dict[str, Any] = {"service": service, "country": country, "price": 1}
+        if operator:
+            params["operator"] = operator
+
+        data = self._request("/api/getCountNumber/", params)
+        if isinstance(data, dict):
+            cnt = data.get(service, 0)
+            price = data.get("price")
+            return CountNumber(
+                service=service,
+                count=int(cnt) if isinstance(cnt, (int, float)) else 0,
+                price=float(price) if isinstance(price, (int, float)) else None,
+            )
+        raise VakSmsError("Invalid getCountNumber response", "INVALID_RESPONSE", data)
+
+    def get_country_list(self) -> list[CountryOperator]:
+        """Retrieves catalog of supported countries and available operators.
+
+        Returns:
+            List of CountryOperator objects.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> countries = client.get_country_list()
+            >>> print(f"Supported countries: {len(countries)}")
+        """
+        data = self._request("/api/getCountryList/")
+        if isinstance(data, list):
+            res: list[CountryOperator] = []
+            for item in data:
+                if isinstance(item, dict):
+                    res.append(
+                        CountryOperator(
+                            country_name=item.get("countryName", ""),
+                            country_code=item.get("countryCode", ""),
+                            operator_list=item.get("operatorList", []),
+                        )
+                    )
+            return res
+        raise VakSmsError("Invalid getCountryList response", "INVALID_RESPONSE", data)
+
+    def get_count_numbers_list(
+        self,
+        country: str = "ru",
+        operator: str | None = None,
+        rent: bool = False,
+    ) -> dict[str, Any]:
+        """Retrieves full service inventory for a country.
+
+        Args:
+            country: Country code (default 'ru').
+            operator: Optional network operator name.
+            rent: Whether to query extended rental stock.
+
+        Returns:
+            Dictionary of services, quantities, and pricing.
+
+        Examples:
+            >>> client = VakSmsClient(api_key="key")
+            >>> catalog = client.get_count_numbers_list("ru")
+        """
+        params: dict[str, Any] = {"country": country}
+        if operator:
+            params["operator"] = operator
+        if rent:
+            params["rent"] = "true"
+
+        data = self._request("/api/getCountNumbersList/", params)
+        return data if isinstance(data, dict) else {}
+
+    def _request(self, endpoint: str, params: dict[str, Any] | None = None) -> Any:
+        query: dict[str, Any] = {"apiKey": self.api_key}
+        if params:
+            query.update(params)
+
+        try:
+            resp = self._client.get(endpoint, params=query)
+            resp.raise_for_status()
+            data = resp.json()
+
+            if isinstance(data, dict):
+                if "error" in data and data["error"]:
+                    err_code = str(data["error"])
+                    desc = ERROR_DESCRIPTIONS.get(err_code, f"VAK-SMS API error: {err_code}")
+                    raise VakSmsError(desc, code=err_code, response_body=data)
+                if "code" in data and data.get("code") and "message" in data:
+                    raise VakSmsError(
+                        str(data["message"]), code=str(data["code"]), response_body=data
+                    )
+
+            return data
+        except httpx.HTTPError as exc:
+            raise VakSmsError(f"HTTP request failed: {exc}", "NETWORK_ERROR") from exc

vak_sms/errors.py

@@ -0,0 +1,30 @@
+"""Error definitions for the VAK-SMS client."""
+
+from typing import Any
+
+ERROR_DESCRIPTIONS: dict[str, str] = {
+    "apiKeyNotFound": "API key not found",
+    "noService": "Service not found or invalid",
+    "noNumber": "No numbers available, try again later",
+    "noMoney": "Insufficient funds, please top up balance",
+    "noCountry": "Country not found",
+    "noOperator": "No operator was found for requested country",
+    "badStatus": "Status code not correct",
+    "idNumNotFound": "Activation idNum not found",
+    "badService": "Incorrect website or service code",
+    "badData": "Invalid request data sent",
+}
+
+
+class VakSmsError(Exception):
+    """Exception raised when a VAK-SMS API request fails."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        response_body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.response_body = response_body

vak_sms/types.py

@@ -0,0 +1,31 @@
+"""Data types for the VAK-SMS API."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class VakNumber:
+    """Represents an acquired temporary phone number."""
+
+    id_num: str
+    tel: str
+    service: str | None = None
+    rent: bool = False
+
+
+@dataclass
+class CountNumber:
+    """Stock count and pricing for a service."""
+
+    service: str
+    count: int
+    price: float | None = None
+
+
+@dataclass
+class CountryOperator:
+    """Supported country and list of available mobile operators."""
+
+    country_name: str
+    country_code: str
+    operator_list: list[str]

vaksms_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: vaksms-client
+Version: 0.2.0
+Summary: Python client for the VAK-SMS virtual number and SMS activation API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://vak-sms.com/en/api/
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# vaksms-client
+
+[![PyPI version](https://img.shields.io/pypi/v/vaksms-client.svg)](https://pypi.org/project/vaksms-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/pypi/pyversions/vaksms-client.svg)](https://pypi.org/project/vaksms-client/)
+
+Modern, fully typed Python client library for the [VAK-SMS](https://vak-sms.com/api/) virtual phone numbers and SMS OTP receiving service.
+
+Official API documentation: <https://vak-sms.com/api/vak/>
+
+Install as `vaksms-client` (`pip install vaksms-client`); import as `vak_sms`.
+
+---
+
+## Features
+
+- 📱 **Virtual Phone Numbers** — Disposable phone numbers across dozens of countries for Telegram, WhatsApp, Discord, Google, and 100+ services.
+- 🔁 **Number Prolongation** — Re-rent or prolong previously used numbers for secondary SMS verification.
+- ⏳ **Built-in Auto Polling** — `wait_for_code()` automatically polls until the SMS verification code is received or timeout is reached.
+- 🐍 **Modern Pythonic Design** — Type annotations, dataclass models (`VakNumber`, `CountryOperator`), context manager support (`with VakSmsClient(...) as client:`), and custom exceptions.
+
+---
+
+## Installation
+
+```bash
+pip install vaksms-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects your account balance and supported countries. It does not order numbers or consume funds:
+
+```python
+import os
+from vak_sms import VakSmsClient
+
+with VakSmsClient(api_key=os.environ["VAK_SMS_API_KEY"]) as client:
+    balance = client.get_balance()
+    print(f"Current VAK-SMS balance: {balance:.2f} RUB")
+
+    countries = client.get_country_list()
+    print(f"Supported countries count: {len(countries)}")
+```
+
+---
+
+## Usage Guide
+
+### 1. Renting a Number and Receiving an SMS Code
+
+Full activation lifecycle: order a number, wait for the incoming SMS verification code, and finish the activation:
+
+```python
+from vak_sms import VakSmsClient, VakSmsError
+
+with VakSmsClient(api_key="your_api_key") as client:
+    # 1. Order a number for Telegram in United States ('us')
+    order = client.get_number(service="tg", country="us")
+    print(f"Rented Number: +{order.tel} (ID: {order.id_num})")
+
+    # 2. Poll for the incoming verification code using built-in helper
+    try:
+        code = client.wait_for_code(order.id_num, timeout_ms=120_000, interval_ms=3_000)
+        print(f"Received verification code: {code}")
+
+        # 3. Mark activation successfully finished ('end')
+        client.set_status(order.id_num, "end")
+    except VakSmsError as err:
+        if err.code == "TIMEOUT":
+            print("SMS did not arrive in time. Marking as bad number ('bad')...")
+            client.set_status(order.id_num, "bad")
+        else:
+            raise err
+```
+
+### 2. Requesting Repeat / Second SMS ('send')
+
+If you need a second SMS message on the same rented number:
+
+```python
+# Notify provider that you want to receive another SMS code
+client.set_status(order.id_num, "send")
+
+# Wait for the second code
+second_code = client.wait_for_code(order.id_num)
+print(f"Second code: {second_code}")
+
+# Finish
+client.set_status(order.id_num, "end")
+```
+
+### 3. Number Prolongation (Re-using Previous Number)
+
+Prolong an existing number for a service if it is still available on the SIM farm:
+
+```python
+prolonged = client.prolong_number("tg", order.id_num)
+print(f"Prolonged number: +{prolonged.tel}")
+```
+
+### 4. Inspecting Stock Availability
+
+Check available numbers for a service:
+
+```python
+# Count available numbers for Telegram in USA
+count = client.get_count_number("tg", "us")
+print(f"Available numbers: {count}")
+
+# All service counts in a country
+numbers_list = client.get_count_numbers_list("us")
+print("USA counts by service:", numbers_list)
+```
+
+---
+
+## API Reference
+
+### `VakSmsClient` Class
+
+#### Constructor
+
+```python
+VakSmsClient(
+    api_key: str,
+    base_url: str = "https://vak-sms.com",
+    timeout: float = 30.0,
+)
+```
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `api_key` | `str` | **Required** | Your VAK-SMS API key. |
+| `base_url` | `str` | `"https://vak-sms.com"` | Base URL of VAK-SMS API. |
+| `timeout` | `float` | `30.0` | Request timeout in seconds. |
+
+#### Methods
+
+- **`get_balance() -> float`** — Returns account balance in RUB.
+- **`get_number(service, country=None, operator=None) -> VakNumber`** — Orders a phone number (`tel`, `id_num`).
+- **`prolong_number(service, id_num, operator=None) -> VakNumber`** — Re-activates a previous number.
+- **`get_sms_code(id_num, all=False) -> str | list[str] | None`** — Checks for incoming SMS code (`None` if waiting).
+- **`wait_for_code(id_num, timeout_ms=120000, interval_ms=3000) -> str`** — Automatically polls until code arrives.
+- **`set_status(id_num: str, status: str) -> str`** — Sets activation state (`'send'`, `'end'`, `'bad'`).
+- **`get_count_number(service, country=None, operator=None) -> int`** — Available numbers for a service.
+- **`get_country_list() -> list[CountryOperator]`** — Lists supported countries and operators.
+- **`get_count_numbers_list(country=None, operator=None) -> dict[str, int]`** — Map of service counts.
+
+---
+
+## Error Handling
+
+When the API returns an error response, `VakSmsError` is raised:
+
+```python
+from vak_sms import VakSmsClient, VakSmsError
+
+try:
+    with VakSmsClient(api_key="invalid_key") as client:
+        client.get_balance()
+except VakSmsError as exc:
+    print(f"VAK-SMS Error: {exc.message} (Code: {exc.code})")
+```
+
+Common error codes:
+- `noNumber` — No numbers currently available for the service/country.
+- `noMoney` — Insufficient balance on account.
+- `apiKeyNotFound` — Invalid API key.
+- `badStatus` — Invalid status passed.
+- `TIMEOUT` — Polling timeout exceeded in `wait_for_code()`.
+
+---
+
+## License
+
+ISC

vaksms_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+vak_sms/__init__.py,sha256=MFjL6gx1e_QVchAgsAfIhDbktQDMN6Gva2jWVtmArzo,307
+vak_sms/client.py,sha256=kvBj9JSdmADsLwUWUp12X5RuhCFBP6TqJHzgLBi-_1c,12524
+vak_sms/errors.py,sha256=MT_Pbtx2yyrF825LMYvFb69DU89fBSlVO29r7MYrPIo,960
+vak_sms/types.py,sha256=YPIpaxiFGXKXe11Fn4gBe8dorZZmPc66gFv3CYxN6M8,567
+vaksms_client-0.2.0.dist-info/METADATA,sha256=mv-2VywqM78jpjWSKLinP6vGl8y28sYu61M1xrp4D9Y,6270
+vaksms_client-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+vaksms_client-0.2.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+vaksms_client-0.2.0.dist-info/RECORD,,

vaksms_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

vaksms_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.