mrxsim 1.0.0__tar.gz

mrxsim-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MRXSIM
+
+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.

mrxsim-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: mrxsim
+Version: 1.0.0
+Summary: Official Python client for MRXSIM.COM — secure SMS number purchasing & OTP retrieval
+Author-email: MRXSIM <whomrxami@pm.me>
+Maintainer-email: MRXSIM <whomrxami@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://mrxsim.com
+Project-URL: Documentation, https://mrxsim.com/docs
+Project-URL: Repository, https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation
+Project-URL: Bug Tracker, https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues
+Keywords: mrxsim,sms,otp,virtual-number,telegram,whatsapp,automation,api-client
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: async
+Requires-Dist: aiohttp<4,>=3.9.0; extra == "async"
+Provides-Extra: cli
+Requires-Dist: colorama<1,>=0.4.6; extra == "cli"
+Dynamic: license-file
+
+# mrxsim
+
+Official Python client for **[MRXSIM.COM](https://mrxsim.com)** — purchase virtual numbers and retrieve SMS OTPs for every catalog service (Telegram, WhatsApp, Google, Instagram, PayPal, Snapchat, Other (SMS), and more).
+
+> Brand: **MRXSIM** · Domain: **https://mrxsim.com** · Package: **`mrxsim`**
+
+---
+
+## Security first
+
+- **No hardcoded API keys** in library source or examples.
+- Prefer environment variable ``MRXSIM_API_KEY``.
+- Or load a local ``config.json`` that is **gitignored**.
+- Never commit live keys. Revoke immediately if exposed.
+
+---
+
+## Install
+
+```bash
+pip install mrxsim
+```
+
+From this repository (editable):
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick start (environment variable)
+
+```bash
+export MRXSIM_API_KEY="mrxs_your_key_here"   # Linux / macOS
+# setx MRXSIM_API_KEY "mrxs_your_key_here"  # Windows (new shell)
+```
+
+```python
+from mrxsim import Client
+
+with Client(country="england", service="telegram") as client:
+    order = client.get_number()
+    print(order["phone_number"], order["id"])
+
+    sms = client.wait_for_sms(order["id"])
+    print(sms["sms_code"])
+```
+
+One-shot purchase + OTP:
+
+```python
+from mrxsim import Client
+
+with Client(country="egypt", service="whatsapp") as client:
+    result = client.buy_and_wait()
+    print(result["phone_number"], result["sms_code"])
+```
+
+---
+
+## Quick start (config file)
+
+```bash
+cp config.example.json config.json
+# edit config.json → set api_key, country, service
+```
+
+```python
+from mrxsim import Client
+
+client = Client.from_config("config.json")
+order = client.get_number()
+sms = client.wait_for_sms(order["id"])
+client.close()
+```
+
+``MRXSIM_API_KEY`` overrides ``api_key`` in the file when set.
+
+---
+
+## Get your API key
+
+1. Open [https://mrxsim.com](https://mrxsim.com) and create an account.
+2. Top up with **Crypto** (USDT / supported networks).
+3. **Profile → Get API KEY** (shown once at create/regenerate).
+4. Export ``MRXSIM_API_KEY`` or paste into gitignored ``config.json``.
+
+---
+
+## API surface
+
+| Method | Endpoint | Client method |
+|--------|----------|---------------|
+| `POST` | `/api/v1/get_number` | `Client.get_number()` |
+| `GET` | `/api/v1/get_sms?order_id=…` | `Client.get_sms()` / `wait_for_sms()` |
+
+Header on every call:
+
+```http
+X-API-Key: YOUR_KEY
+```
+
+Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+
+---
+
+## Examples
+
+```bash
+export MRXSIM_API_KEY="…"
+python examples/buy_number_example.py
+python examples/get_otp_example.py <order_id>
+```
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+---
+
+## Support
+
+- Site: [https://mrxsim.com](https://mrxsim.com)
+- Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+- Issues: [GitHub](https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues)
+
+© MRXSIM · Secure SMS Infrastructure

mrxsim-1.0.0/README.md

@@ -0,0 +1,137 @@
+# mrxsim
+
+Official Python client for **[MRXSIM.COM](https://mrxsim.com)** — purchase virtual numbers and retrieve SMS OTPs for every catalog service (Telegram, WhatsApp, Google, Instagram, PayPal, Snapchat, Other (SMS), and more).
+
+> Brand: **MRXSIM** · Domain: **https://mrxsim.com** · Package: **`mrxsim`**
+
+---
+
+## Security first
+
+- **No hardcoded API keys** in library source or examples.
+- Prefer environment variable ``MRXSIM_API_KEY``.
+- Or load a local ``config.json`` that is **gitignored**.
+- Never commit live keys. Revoke immediately if exposed.
+
+---
+
+## Install
+
+```bash
+pip install mrxsim
+```
+
+From this repository (editable):
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick start (environment variable)
+
+```bash
+export MRXSIM_API_KEY="mrxs_your_key_here"   # Linux / macOS
+# setx MRXSIM_API_KEY "mrxs_your_key_here"  # Windows (new shell)
+```
+
+```python
+from mrxsim import Client
+
+with Client(country="england", service="telegram") as client:
+    order = client.get_number()
+    print(order["phone_number"], order["id"])
+
+    sms = client.wait_for_sms(order["id"])
+    print(sms["sms_code"])
+```
+
+One-shot purchase + OTP:
+
+```python
+from mrxsim import Client
+
+with Client(country="egypt", service="whatsapp") as client:
+    result = client.buy_and_wait()
+    print(result["phone_number"], result["sms_code"])
+```
+
+---
+
+## Quick start (config file)
+
+```bash
+cp config.example.json config.json
+# edit config.json → set api_key, country, service
+```
+
+```python
+from mrxsim import Client
+
+client = Client.from_config("config.json")
+order = client.get_number()
+sms = client.wait_for_sms(order["id"])
+client.close()
+```
+
+``MRXSIM_API_KEY`` overrides ``api_key`` in the file when set.
+
+---
+
+## Get your API key
+
+1. Open [https://mrxsim.com](https://mrxsim.com) and create an account.
+2. Top up with **Crypto** (USDT / supported networks).
+3. **Profile → Get API KEY** (shown once at create/regenerate).
+4. Export ``MRXSIM_API_KEY`` or paste into gitignored ``config.json``.
+
+---
+
+## API surface
+
+| Method | Endpoint | Client method |
+|--------|----------|---------------|
+| `POST` | `/api/v1/get_number` | `Client.get_number()` |
+| `GET` | `/api/v1/get_sms?order_id=…` | `Client.get_sms()` / `wait_for_sms()` |
+
+Header on every call:
+
+```http
+X-API-Key: YOUR_KEY
+```
+
+Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+
+---
+
+## Examples
+
+```bash
+export MRXSIM_API_KEY="…"
+python examples/buy_number_example.py
+python examples/get_otp_example.py <order_id>
+```
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+---
+
+## Support
+
+- Site: [https://mrxsim.com](https://mrxsim.com)
+- Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+- Issues: [GitHub](https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues)
+
+© MRXSIM · Secure SMS Infrastructure

mrxsim-1.0.0/mrxsim/__init__.py

@@ -0,0 +1,34 @@
+"""
+MRXSIM — Official Python client for https://mrxsim.com
+
+Secure SMS number purchasing and OTP retrieval for every MRXSIM catalog service.
+"""
+
+from __future__ import annotations
+
+from mrxsim.client import Client, MrxsimClient, load_config
+from mrxsim.exceptions import (
+    MrxsimAPIError,
+    MrxsimAuthError,
+    MrxsimConfigError,
+    MrxsimError,
+    MrxsimOrderError,
+    MrxsimRateLimitError,
+    MrxsimTimeoutError,
+)
+
+__all__ = [
+    "Client",
+    "MrxsimClient",
+    "load_config",
+    "MrxsimError",
+    "MrxsimConfigError",
+    "MrxsimAuthError",
+    "MrxsimAPIError",
+    "MrxsimTimeoutError",
+    "MrxsimRateLimitError",
+    "MrxsimOrderError",
+]
+
+__version__ = "1.0.0"
+__author__ = "MRXSIM"

mrxsim-1.0.0/mrxsim/client.py

@@ -0,0 +1,452 @@
+"""
+MRXSIM synchronous HTTP client.
+
+Authentication is never hardcoded. Provide credentials via:
+
+* Environment variable ``MRXSIM_API_KEY``
+* Explicit ``api_key=`` constructor argument
+* A local config file (e.g. ``config.json``) loaded with :meth:`Client.from_config`
+
+© MRXSIM · https://mrxsim.com
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Mapping
+from urllib.parse import urljoin
+
+import requests
+
+from mrxsim.exceptions import (
+    MrxsimAPIError,
+    MrxsimAuthError,
+    MrxsimConfigError,
+    MrxsimError,
+    MrxsimOrderError,
+    MrxsimRateLimitError,
+    MrxsimTimeoutError,
+)
+
+DEFAULT_BASE_URL = "https://mrxsim.com"
+DEFAULT_USER_AGENT = "mrxsim-python/1.0.0 (+https://mrxsim.com)"
+ENV_API_KEY = "MRXSIM_API_KEY"
+ENV_BASE_URL = "MRXSIM_BASE_URL"
+
+_TERMINAL_FAIL = frozenset({"CANCELED", "CANCELLED", "EXPIRED", "TIMEOUT", "FAILED"})
+
+
+def _require_nonempty(value: str | None, field: str) -> str:
+    text = (value or "").strip()
+    if not text:
+        raise MrxsimConfigError(f"Missing required configuration: {field}")
+    return text
+
+
+def _normalize_base_url(url: str) -> str:
+    return url.strip().rstrip("/")
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    """
+    Load a JSON configuration file.
+
+    The file must be a JSON object. ``api_key`` may be omitted if
+    ``MRXSIM_API_KEY`` is set in the environment.
+
+    Parameters
+    ----------
+    path:
+        Filesystem path to the JSON config (e.g. ``config.json``).
+
+    Returns
+    -------
+    dict[str, Any]
+        Parsed configuration mapping.
+
+    Raises
+    ------
+    MrxsimConfigError
+        If the file is missing or not a valid JSON object.
+    """
+    cfg_path = Path(path).expanduser().resolve()
+    if not cfg_path.is_file():
+        raise MrxsimConfigError(
+            f"Config file not found: {cfg_path}. "
+            "Copy config.example.json → config.json and set your API key, "
+            "or export MRXSIM_API_KEY."
+        )
+    try:
+        with cfg_path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except json.JSONDecodeError as exc:
+        raise MrxsimConfigError(f"Invalid JSON in {cfg_path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise MrxsimConfigError(f"Config file must be a JSON object: {cfg_path}")
+    return data
+
+
+class Client:
+    """
+    Production client for the MRXSIM.COM public SMS API.
+
+    Supports every catalog service (Telegram, WhatsApp, Google, Instagram,
+    PayPal, Snapchat, Other (SMS), and more).
+
+    Parameters
+    ----------
+    api_key:
+        MRXSIM API key. If omitted, read from ``MRXSIM_API_KEY``.
+    base_url:
+        API origin. Defaults to ``https://mrxsim.com`` or ``MRXSIM_BASE_URL``.
+    country:
+        Default catalog country code (e.g. ``england``, ``usa``, ``egypt``).
+    service:
+        Default service code (e.g. ``telegram``, ``whatsapp``, ``other``).
+    operator:
+        Default operator stack (``any`` or a specific stack id).
+    timeout:
+        Default HTTP request timeout in seconds.
+    poll_interval:
+        Default seconds between OTP polls.
+    poll_timeout:
+        Default maximum seconds to wait for an OTP.
+    session:
+        Optional pre-configured :class:`requests.Session`.
+
+    Raises
+    ------
+    MrxsimConfigError
+        If no API key can be resolved.
+    MrxsimAuthError
+        If the resolved key looks like an unreplaced placeholder.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        country: str | None = None,
+        service: str | None = None,
+        operator: str = "any",
+        timeout: float = 30.0,
+        poll_interval: float = 3.0,
+        poll_timeout: float = 600.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        resolved_key = (api_key or os.environ.get(ENV_API_KEY) or "").strip()
+        if not resolved_key:
+            raise MrxsimConfigError(
+                "API key required. Pass api_key=, set MRXSIM_API_KEY, "
+                "or use Client.from_config('config.json'). "
+                "Generate a key at https://mrxsim.com"
+            )
+        if resolved_key.startswith("REPLACE_") or resolved_key in {
+            "mrxs_your_key_here",
+            "YOUR_KEY",
+            "changeme",
+        }:
+            raise MrxsimAuthError(
+                "Placeholder API key detected. Set a real key from https://mrxsim.com"
+            )
+
+        env_base = os.environ.get(ENV_BASE_URL)
+        self.base_url = _normalize_base_url(
+            base_url or env_base or DEFAULT_BASE_URL
+        )
+        self.country = (country or "").strip().lower() or None
+        self.service = (service or "").strip().lower() or None
+        self.operator = ((operator or "any").strip().lower() or "any")
+        self.timeout = max(5.0, float(timeout))
+        self.poll_interval = max(1.0, float(poll_interval))
+        self.poll_timeout = max(30.0, float(poll_timeout))
+
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": resolved_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": DEFAULT_USER_AGENT,
+            }
+        )
+        # Never keep a public attribute that echoes the key.
+        self._api_key_fingerprint = f"{resolved_key[:6]}…{resolved_key[-4:]}" if len(resolved_key) > 12 else "***"
+
+    @classmethod
+    def from_config(
+        cls,
+        path: str | Path = "config.json",
+        *,
+        session: requests.Session | None = None,
+    ) -> Client:
+        """
+        Construct a client from a JSON config file.
+
+        Environment variable ``MRXSIM_API_KEY`` overrides ``api_key`` in the file
+        when set (prefer secrets outside the working tree).
+
+        Parameters
+        ----------
+        path:
+            Path to the JSON config file.
+        session:
+            Optional shared :class:`requests.Session`.
+        """
+        raw = load_config(path)
+        api_key = os.environ.get(ENV_API_KEY) or str(raw.get("api_key") or "")
+        return cls(
+            api_key=api_key or None,
+            base_url=str(raw.get("base_url") or DEFAULT_BASE_URL),
+            country=str(raw.get("country") or "") or None,
+            service=str(raw.get("service") or "") or None,
+            operator=str(raw.get("operator") or "any"),
+            timeout=float(raw.get("request_timeout_seconds") or 30),
+            poll_interval=float(raw.get("poll_interval_seconds") or 3),
+            poll_timeout=float(raw.get("poll_timeout_seconds") or 600),
+            session=session,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _url(self, path: str) -> str:
+        return urljoin(f"{self.base_url}/", path.lstrip("/"))
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        try:
+            response = self._session.request(
+                method=method.upper(),
+                url=self._url(path),
+                json=dict(json_body) if json_body is not None else None,
+                params=dict(params) if params is not None else None,
+                timeout=timeout if timeout is not None else self.timeout,
+            )
+        except requests.Timeout as exc:
+            raise MrxsimTimeoutError(f"HTTP request timed out: {method} {path}") from exc
+        except requests.RequestException as exc:
+            raise MrxsimError(f"HTTP transport error: {exc}") from exc
+        return self._parse(response)
+
+    @staticmethod
+    def _parse(response: requests.Response) -> dict[str, Any]:
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = {"error": (response.text or "")[:300]}
+
+        if response.status_code in {401, 403}:
+            detail = body.get("detail") if isinstance(body, dict) else body
+            raise MrxsimAuthError(
+                f"Authentication failed (HTTP {response.status_code}): {detail}",
+                details=detail,
+            )
+        if response.status_code == 429:
+            detail = body.get("detail") if isinstance(body, dict) else body
+            raise MrxsimRateLimitError(
+                f"Rate limited (HTTP 429): {detail}",
+                status_code=429,
+                details=detail,
+            )
+        if response.status_code >= 400:
+            detail: Any
+            if isinstance(body, dict):
+                raw_detail = body.get("detail", body)
+                if isinstance(raw_detail, dict):
+                    detail = raw_detail.get("error") or raw_detail
+                else:
+                    detail = raw_detail
+            else:
+                detail = body
+            raise MrxsimAPIError(
+                f"HTTP {response.status_code}: {detail}",
+                status_code=response.status_code,
+                details=detail,
+            )
+        if not isinstance(body, dict):
+            raise MrxsimAPIError(
+                "Unexpected API response (expected JSON object)",
+                status_code=response.status_code,
+                details=body,
+            )
+        return body
+
+    def get_number(
+        self,
+        *,
+        country: str | None = None,
+        service: str | None = None,
+        operator: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Purchase a virtual number for a country/service pair.
+
+        Parameters
+        ----------
+        country:
+            Catalog country. Falls back to the client default.
+        service:
+            Catalog service. Falls back to the client default.
+        operator:
+            Operator stack. Falls back to the client default (``any``).
+
+        Returns
+        -------
+        dict[str, Any]
+            Order payload including ``id``, ``phone_number``, ``price``, ``status``.
+        """
+        resolved_country = _require_nonempty(country or self.country, "country")
+        resolved_service = _require_nonempty(service or self.service, "service")
+        resolved_operator = (
+            (operator if operator is not None else self.operator) or "any"
+        ).strip().lower() or "any"
+
+        return self._request(
+            "POST",
+            "/api/v1/get_number",
+            json_body={
+                "country": resolved_country.lower(),
+                "service": resolved_service.lower(),
+                "operator": resolved_operator,
+            },
+        )
+
+    def get_sms(self, order_id: str) -> dict[str, Any]:
+        """
+        Fetch the current SMS/OTP status for an order.
+
+        Parameters
+        ----------
+        order_id:
+            Order identifier returned by :meth:`get_number`.
+
+        Returns
+        -------
+        dict[str, Any]
+            Status payload; may include ``sms_code`` when received.
+        """
+        oid = _require_nonempty(order_id, "order_id")
+        return self._request(
+            "GET",
+            "/api/v1/get_sms",
+            params={"order_id": oid},
+        )
+
+    def wait_for_sms(
+        self,
+        order_id: str,
+        *,
+        poll_interval: float | None = None,
+        poll_timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """
+        Poll until an OTP is received or the order fails / times out.
+
+        Parameters
+        ----------
+        order_id:
+            Order identifier from :meth:`get_number`.
+        poll_interval:
+            Seconds between polls (default: client ``poll_interval``).
+        poll_timeout:
+            Maximum wait in seconds (default: client ``poll_timeout``).
+
+        Returns
+        -------
+        dict[str, Any]
+            Final SMS payload containing ``sms_code`` when successful.
+
+        Raises
+        ------
+        MrxsimOrderError
+            If the order reaches a terminal failure status.
+        MrxsimTimeoutError
+            If no OTP arrives before ``poll_timeout``.
+        """
+        oid = _require_nonempty(order_id, "order_id")
+        interval = max(1.0, float(poll_interval if poll_interval is not None else self.poll_interval))
+        deadline = time.monotonic() + max(
+            30.0, float(poll_timeout if poll_timeout is not None else self.poll_timeout)
+        )
+
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            row = self.get_sms(oid)
+            status = str(row.get("status") or "").upper()
+            code = str(row.get("sms_code") or "").strip()
+            if code or status == "RECEIVED":
+                return row
+            if status in _TERMINAL_FAIL:
+                raise MrxsimOrderError(
+                    f"Order {oid} ended with status={status}",
+                    status=status,
+                )
+
+        raise MrxsimTimeoutError(
+            f"Timed out waiting for SMS on order {oid}"
+        )
+
+    def buy_and_wait(
+        self,
+        *,
+        country: str | None = None,
+        service: str | None = None,
+        operator: str | None = None,
+        poll_interval: float | None = None,
+        poll_timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """
+        Purchase a number and block until the OTP arrives.
+
+        Returns
+        -------
+        dict[str, Any]
+            Combined result with ``order``, ``phone_number``, ``sms_code``, and ``status``.
+        """
+        order = self.get_number(country=country, service=service, operator=operator)
+        order_id = str(order.get("id") or "")
+        if not order_id:
+            raise MrxsimAPIError("Purchase succeeded but no order id was returned", details=order)
+        sms = self.wait_for_sms(
+            order_id,
+            poll_interval=poll_interval,
+            poll_timeout=poll_timeout,
+        )
+        return {
+            "order": order,
+            "order_id": order_id,
+            "phone_number": sms.get("phone_number") or order.get("phone_number"),
+            "sms_code": str(sms.get("sms_code") or "").strip(),
+            "status": sms.get("status") or order.get("status"),
+            "sms": sms,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"Client(base_url={self.base_url!r}, "
+            f"country={self.country!r}, service={self.service!r}, "
+            f"key={self._api_key_fingerprint!r})"
+        )
+
+
+# Backwards-compatible alias used by early automation scripts.
+MrxsimClient = Client

mrxsim-1.0.0/mrxsim/exceptions.py

@@ -0,0 +1,55 @@
+"""Custom exception hierarchy for the MRXSIM public API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MrxsimError(Exception):
+    """Base exception for all MRXSIM client errors."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class MrxsimConfigError(MrxsimError):
+    """Raised when configuration is missing, invalid, or insecure."""
+
+
+class MrxsimAuthError(MrxsimError):
+    """Raised when the API key is missing, invalid, or unauthorized (HTTP 401/403)."""
+
+
+class MrxsimAPIError(MrxsimError):
+    """Raised for non-success HTTP responses from the MRXSIM API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        details: Any | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.status_code = status_code
+
+
+class MrxsimTimeoutError(MrxsimError):
+    """Raised when an HTTP request or OTP poll exceeds the configured timeout."""
+
+
+class MrxsimRateLimitError(MrxsimAPIError):
+    """Raised when the API returns HTTP 429 (rate limited)."""
+
+
+class MrxsimOrderError(MrxsimError):
+    """Raised when an order ends in a terminal failure state."""
+
+    def __init__(self, message: str, *, status: str | None = None) -> None:
+        super().__init__(message, details={"status": status} if status else None)
+        self.status = status

mrxsim-1.0.0/mrxsim/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 typed package

mrxsim-1.0.0/mrxsim.egg-info/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: mrxsim
+Version: 1.0.0
+Summary: Official Python client for MRXSIM.COM — secure SMS number purchasing & OTP retrieval
+Author-email: MRXSIM <whomrxami@pm.me>
+Maintainer-email: MRXSIM <whomrxami@pm.me>
+License-Expression: MIT
+Project-URL: Homepage, https://mrxsim.com
+Project-URL: Documentation, https://mrxsim.com/docs
+Project-URL: Repository, https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation
+Project-URL: Bug Tracker, https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues
+Keywords: mrxsim,sms,otp,virtual-number,telegram,whatsapp,automation,api-client
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: async
+Requires-Dist: aiohttp<4,>=3.9.0; extra == "async"
+Provides-Extra: cli
+Requires-Dist: colorama<1,>=0.4.6; extra == "cli"
+Dynamic: license-file
+
+# mrxsim
+
+Official Python client for **[MRXSIM.COM](https://mrxsim.com)** — purchase virtual numbers and retrieve SMS OTPs for every catalog service (Telegram, WhatsApp, Google, Instagram, PayPal, Snapchat, Other (SMS), and more).
+
+> Brand: **MRXSIM** · Domain: **https://mrxsim.com** · Package: **`mrxsim`**
+
+---
+
+## Security first
+
+- **No hardcoded API keys** in library source or examples.
+- Prefer environment variable ``MRXSIM_API_KEY``.
+- Or load a local ``config.json`` that is **gitignored**.
+- Never commit live keys. Revoke immediately if exposed.
+
+---
+
+## Install
+
+```bash
+pip install mrxsim
+```
+
+From this repository (editable):
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick start (environment variable)
+
+```bash
+export MRXSIM_API_KEY="mrxs_your_key_here"   # Linux / macOS
+# setx MRXSIM_API_KEY "mrxs_your_key_here"  # Windows (new shell)
+```
+
+```python
+from mrxsim import Client
+
+with Client(country="england", service="telegram") as client:
+    order = client.get_number()
+    print(order["phone_number"], order["id"])
+
+    sms = client.wait_for_sms(order["id"])
+    print(sms["sms_code"])
+```
+
+One-shot purchase + OTP:
+
+```python
+from mrxsim import Client
+
+with Client(country="egypt", service="whatsapp") as client:
+    result = client.buy_and_wait()
+    print(result["phone_number"], result["sms_code"])
+```
+
+---
+
+## Quick start (config file)
+
+```bash
+cp config.example.json config.json
+# edit config.json → set api_key, country, service
+```
+
+```python
+from mrxsim import Client
+
+client = Client.from_config("config.json")
+order = client.get_number()
+sms = client.wait_for_sms(order["id"])
+client.close()
+```
+
+``MRXSIM_API_KEY`` overrides ``api_key`` in the file when set.
+
+---
+
+## Get your API key
+
+1. Open [https://mrxsim.com](https://mrxsim.com) and create an account.
+2. Top up with **Crypto** (USDT / supported networks).
+3. **Profile → Get API KEY** (shown once at create/regenerate).
+4. Export ``MRXSIM_API_KEY`` or paste into gitignored ``config.json``.
+
+---
+
+## API surface
+
+| Method | Endpoint | Client method |
+|--------|----------|---------------|
+| `POST` | `/api/v1/get_number` | `Client.get_number()` |
+| `GET` | `/api/v1/get_sms?order_id=…` | `Client.get_sms()` / `wait_for_sms()` |
+
+Header on every call:
+
+```http
+X-API-Key: YOUR_KEY
+```
+
+Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+
+---
+
+## Examples
+
+```bash
+export MRXSIM_API_KEY="…"
+python examples/buy_number_example.py
+python examples/get_otp_example.py <order_id>
+```
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+---
+
+## Support
+
+- Site: [https://mrxsim.com](https://mrxsim.com)
+- Docs: [https://mrxsim.com/docs](https://mrxsim.com/docs)
+- Issues: [GitHub](https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues)
+
+© MRXSIM · Secure SMS Infrastructure

mrxsim-1.0.0/mrxsim.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+mrxsim/__init__.py
+mrxsim/client.py
+mrxsim/exceptions.py
+mrxsim/py.typed
+mrxsim.egg-info/PKG-INFO
+mrxsim.egg-info/SOURCES.txt
+mrxsim.egg-info/dependency_links.txt
+mrxsim.egg-info/requires.txt
+mrxsim.egg-info/top_level.txt
+tests/test_client.py

mrxsim-1.0.0/mrxsim.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mrxsim-1.0.0/mrxsim.egg-info/requires.txt

@@ -0,0 +1,12 @@
+requests<3,>=2.31.0
+
+[async]
+aiohttp<4,>=3.9.0
+
+[cli]
+colorama<1,>=0.4.6
+
+[dev]
+pytest>=8.0.0
+build>=1.2.0
+twine>=5.0.0

mrxsim-1.0.0/mrxsim.egg-info/top_level.txt

@@ -0,0 +1 @@
+mrxsim

mrxsim-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mrxsim"
+version = "1.0.0"
+description = "Official Python client for MRXSIM.COM — secure SMS number purchasing & OTP retrieval"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "MRXSIM", email = "whomrxami@pm.me" },
+]
+maintainers = [
+    { name = "MRXSIM", email = "whomrxami@pm.me" },
+]
+keywords = [
+    "mrxsim",
+    "sms",
+    "otp",
+    "virtual-number",
+    "telegram",
+    "whatsapp",
+    "automation",
+    "api-client",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.31.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+async = [
+    "aiohttp>=3.9.0,<4",
+]
+cli = [
+    "colorama>=0.4.6,<1",
+]
+
+[project.urls]
+Homepage = "https://mrxsim.com"
+Documentation = "https://mrxsim.com/docs"
+Repository = "https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation"
+"Bug Tracker" = "https://github.com/MRXSIM/MRXSIM-Universal-SMS-Automation/issues"
+
+[tool.setuptools.packages.find]
+include = ["mrxsim*"]
+exclude = ["tests*", "examples*"]
+
+[tool.setuptools.package-data]
+mrxsim = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mrxsim-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mrxsim-1.0.0/tests/test_client.py

@@ -0,0 +1,127 @@
+"""Basic unit tests for mrxsim (no live network / no real API keys)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mrxsim import Client, MrxsimAuthError, MrxsimConfigError, __version__
+from mrxsim.exceptions import MrxsimAPIError, MrxsimRateLimitError
+
+
+def test_version() -> None:
+    assert __version__ == "1.0.0"
+
+
+def test_client_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MRXSIM_API_KEY", raising=False)
+    with pytest.raises(MrxsimConfigError):
+        Client()
+
+
+def test_rejects_placeholder_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MRXSIM_API_KEY", raising=False)
+    with pytest.raises(MrxsimAuthError):
+        Client(api_key="REPLACE_WITH_YOUR_MRXSIM_API_KEY")
+
+
+def test_from_config_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MRXSIM_API_KEY", raising=False)
+    cfg = tmp_path / "config.json"
+    cfg.write_text(
+        json.dumps(
+            {
+                "api_key": "mrxs_test_key_abcdef123456",
+                "base_url": "https://mrxsim.com",
+                "country": "england",
+                "service": "telegram",
+                "operator": "any",
+                "poll_interval_seconds": 3,
+                "poll_timeout_seconds": 600,
+                "request_timeout_seconds": 30,
+            }
+        ),
+        encoding="utf-8",
+    )
+    client = Client.from_config(cfg)
+    assert client.country == "england"
+    assert client.service == "telegram"
+    assert client.base_url == "https://mrxsim.com"
+    client.close()
+
+
+def test_env_overrides_config_key(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    cfg = tmp_path / "config.json"
+    cfg.write_text(
+        json.dumps(
+            {
+                "api_key": "mrxs_file_key_should_not_win",
+                "country": "usa",
+                "service": "whatsapp",
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("MRXSIM_API_KEY", "mrxs_env_key_wins_abcdef")
+    client = Client.from_config(cfg)
+    # Fingerprint should reflect env key prefix, not file key.
+    assert "mrxs_e" in repr(client)
+    client.close()
+
+
+def test_parse_rate_limit() -> None:
+    response = MagicMock()
+    response.status_code = 429
+    response.json.return_value = {"detail": {"error": "slow down"}}
+    with pytest.raises(MrxsimRateLimitError):
+        Client._parse(response)
+
+
+def test_parse_auth_error() -> None:
+    response = MagicMock()
+    response.status_code = 401
+    response.json.return_value = {"detail": "invalid key"}
+    with pytest.raises(MrxsimAuthError):
+        Client._parse(response)
+
+
+def test_get_number_posts_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MRXSIM_API_KEY", "mrxs_unit_test_key_xyz")
+    client = Client(country="egypt", service="telegram")
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {
+        "id": "ord_1",
+        "phone_number": "+201000000000",
+        "price": "0.56",
+        "status": "PENDING",
+    }
+    with patch.object(client._session, "request", return_value=mock_response) as req:
+        order = client.get_number()
+        assert order["id"] == "ord_1"
+        kwargs = req.call_args.kwargs
+        assert kwargs["method"] == "POST"
+        assert kwargs["json"]["country"] == "egypt"
+        assert kwargs["json"]["service"] == "telegram"
+    client.close()
+
+
+def test_get_number_missing_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MRXSIM_API_KEY", "mrxs_unit_test_key_xyz")
+    client = Client()
+    with pytest.raises(MrxsimConfigError):
+        client.get_number()
+    client.close()
+
+
+def test_api_error_body(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MRXSIM_API_KEY", "mrxs_unit_test_key_xyz")
+    response = MagicMock()
+    response.status_code = 422
+    response.json.return_value = {"detail": {"error": "no stock"}}
+    with pytest.raises(MrxsimAPIError) as excinfo:
+        Client._parse(response)
+    assert excinfo.value.status_code == 422