anymessage-sdk 0.2.0__py3-none-any.whl

anymessage/__init__.py

@@ -0,0 +1,132 @@
+# anymessage/__init__.py
+"""
+anymessage — Python SDK for the service https://api.anymessage.shop
+
+The library provides a high-level client `AnyMessageClient`
+and convenient helpers for interacting with the API:
+
+Short-term emails:
+- order a temporary email inbox and wait for a message,
+- reorder or cancel an activation,
+- get the balance and available email inventory.
+
+Long-term emails:
+- buy persistent mailboxes (bulk up to 1000),
+- fetch recent or all messages via the API,
+- look up a purchased mailbox by address.
+
+Activation Rate:
+- get cancel statistics per site+domain pair,
+- enable/disable automatic blocking on low ratio.
+
+API docs: https://anymessage.shop/en/docs
+"""
+
+__version__ = "0.2.0"
+
+# Primary client
+from .client import AnyMessageClient
+
+# Errors (all inherit from AnyMessageError)
+from .errors import (
+    AnyMessageError,
+    AuthError,
+    ValidationError,
+    NotFoundError,
+    NoBalanceError,
+    NoEmailsError,
+    ActivationCanceledError,
+    ActivationAlreadyCanceledError,
+    EmailBannedError,
+    WaitMessageError,
+    RatioBlockError,
+)
+
+# Data models (API responses)
+from .models import (
+    OrderResponse,
+    QuantityResponse,
+    Message,
+    RatioEntry,
+    ImapCredentials,
+    LongliveEmail,
+    LongliveOrderResponse,
+    LongliveMessage,
+)
+
+# High-level API wrappers
+from .methods import (
+    # Short-term email
+    get_balance,
+    get_email_quantity,
+    order_email,
+    reorder_email,
+    cancel_email,
+    get_message,
+    wait_for_message,
+    order_wait_and_extract,
+    # Activation rate
+    get_ratio,
+    enable_block_ratio,
+    disable_block_ratio,
+    # Long-live email
+    get_longlive_quantity,
+    order_longlive_email,
+    get_longlive_history,
+    get_longlive_last_messages,
+    get_longlive_messages,
+    find_longlive_email,
+)
+
+# Utilities
+from .utils import extract_with_regex, domain_param
+
+# Explicitly define the public package interface
+__all__ = (
+    # Client
+    "AnyMessageClient",
+    # Errors
+    "AnyMessageError",
+    "AuthError",
+    "ValidationError",
+    "NotFoundError",
+    "NoBalanceError",
+    "NoEmailsError",
+    "ActivationCanceledError",
+    "ActivationAlreadyCanceledError",
+    "EmailBannedError",
+    "WaitMessageError",
+    "RatioBlockError",
+    # Models
+    "OrderResponse",
+    "QuantityResponse",
+    "Message",
+    "RatioEntry",
+    "ImapCredentials",
+    "LongliveEmail",
+    "LongliveOrderResponse",
+    "LongliveMessage",
+    # Short-term email methods
+    "get_balance",
+    "get_email_quantity",
+    "order_email",
+    "reorder_email",
+    "cancel_email",
+    "get_message",
+    "wait_for_message",
+    "order_wait_and_extract",
+    # Activation rate methods
+    "get_ratio",
+    "enable_block_ratio",
+    "disable_block_ratio",
+    # Long-live email methods
+    "get_longlive_quantity",
+    "order_longlive_email",
+    "get_longlive_history",
+    "get_longlive_last_messages",
+    "get_longlive_messages",
+    "find_longlive_email",
+    # Utilities
+    "extract_with_regex",
+    "domain_param",
+)

anymessage/client.py

@@ -0,0 +1,383 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Callable, Union
+import requests
+
+from .config import DEFAULT_TIMEOUT
+from .errors import AuthError
+
+
+class AnyMessageClient:
+    """
+    High-level client for the AnyMessage API.
+
+    This client encapsulates:
+      • an authorization token,
+      • a reusable HTTP session (requests.Session),
+      • a default network timeout for API calls.
+
+    Recommended usage (context manager):
+
+        >>> from anymessage import AnyMessageClient
+        >>> with AnyMessageClient(token="YOUR_TOKEN") as client:
+        ...     balance = client.get_balance()
+        ...     order = client.order_email(site="instagram.com", domain="gmx")
+        ...     msg = client.wait_for_message(id=order.id, timeout=120, poll_interval=2)
+
+    Thread safety:
+      • create a separate client instance per thread or task;
+      • the library does not use temporary files — everything runs in memory.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        session: Optional[requests.Session] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        """
+        Initialize the client.
+
+        :param token: Required API authorization token.
+        :param session: Optional external requests.Session. If not provided, a new one is created.
+        :param timeout: Default network timeout (in seconds) for all requests.
+        :raises AuthError: If the token is missing.
+        """
+        if not token:
+            raise AuthError("Token must be provided")
+
+        self.token: str = token
+        self.timeout: int = timeout
+
+        # If no external session is provided, create our own and mark it for cleanup.
+        self._own_session: bool = session is None
+        self.session: requests.Session = session or requests.Session()
+
+        # Optionally attach retry adapters for better network stability.
+        try:
+            from .http import mount_retries  # local import to avoid circular dependencies
+            mount_retries(self.session)
+        except Exception:
+            # Fallback: continue without retries if adapters are not available.
+            pass
+
+    # ────────────────────────── Context Manager ──────────────────────────
+
+    def __enter__(self) -> "AnyMessageClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Explicitly close the HTTP session if it was created internally."""
+        if self._own_session and self.session:
+            self.session.close()
+
+    # ─────────────────────────── High-level API Methods ───────────────────────────
+
+    def get_balance(self) -> float:
+        """
+        Retrieve the current user balance.
+
+        Endpoint: GET /user/balance
+        :return: Balance as a float.
+        :raises ApiError/AuthError: On API or authentication errors.
+        """
+        from .methods.balance import _get_balance
+        return _get_balance(self.session, self.token, self.timeout)
+
+    def get_email_quantity(self, *, site: str):
+        """
+        Get available email data for a specific site.
+
+        Endpoint: GET /email/quantity
+        :param site: Target site (e.g., "instagram.com").
+        :return: QuantityResponse
+        :raises ValidationError: If `site` is not provided.
+        :raises ApiError/AuthError: On API or authentication errors.
+        """
+        from .methods.email import _get_email_quantity
+        return _get_email_quantity(self.session, self.token, self.timeout, site=site)
+
+    def order_email(
+        self,
+        *,
+        site: str,
+        domain: str,                       # may include multiple providers: "mailcom,gmx,hotmail"
+        regex: Optional[str] = None,       # regex for extracting part of the message
+        subject: Optional[str] = None,     # subject filter for incoming email
+    ):
+        """
+        Order a temporary email address for the given site/domain.
+
+        Endpoint: GET /email/order
+        :return: OrderResponse (contains id, email, etc.)
+        :raises ValidationError/NoEmailsError/NoBalanceError/ApiError/AuthError
+        """
+        from .methods.email import _order_email
+        return _order_email(
+            self.session,
+            self.token,
+            self.timeout,
+            site=site,
+            domain=domain,
+            regex=regex,
+            subject=subject,
+        )
+
+    def reorder_email(
+        self,
+        *,
+        id: Optional[Union[str, int]] = None,
+        email: Optional[str] = None,
+        site: Optional[str] = None,
+    ):
+        """
+        Reorder email (repeat activation).
+
+        Endpoint: GET /email/reorder
+        Pass either a previous activation `id`, or an `email` + `site` pair.
+
+        :return: OrderResponse
+        :raises ValidationError/ApiError/AuthError
+        """
+        from .methods.email import _reorder_email
+        return _reorder_email(
+            self.session,
+            self.token,
+            self.timeout,
+            id=id,
+            email=email,
+            site=site,
+        )
+
+    def cancel_email(self, *, id: Union[str, int]) -> str:
+        """
+        Cancel an email activation.
+
+        Endpoint: GET /email/cancel
+        :return: Confirmation text (e.g., "activation canceled").
+        :raises ApiError/AuthError
+        """
+        from .methods.email import _cancel_email
+        return _cancel_email(self.session, self.token, self.timeout, id=id)
+
+    def get_message(self, *, id: Union[str, int], preview: bool = False):
+        """
+        Retrieve an email message for a given activation.
+
+        Endpoint: GET /email/getmessage
+
+        API behavior:
+          • preview=False (default) — JSON response, HTML in `message` field;
+          • preview=True — raw HTML (no JSON wrapper).
+        The low-level function normalizes the response into a Message model.
+
+        :return: Message
+        :raises WaitMessageError: If the message is not yet ready (value == "wait message").
+        :raises ApiError/AuthError
+        """
+        from .methods.email import _get_message
+        return _get_message(self.session, self.token, self.timeout, id=id, preview=preview)
+
+    def wait_for_message(
+        self,
+        *,
+        id: Union[str, int],
+        timeout: Union[int, float] = 120,
+        poll_interval: Union[int, float] = 2,
+        preview: bool = False,
+        on_tick: Optional[Callable[[int], None]] = None,
+        stop_event: Optional["object"] = None,   # e.g., threading.Event; use `object` type to avoid hard dependency
+    ):
+        """
+        Wait for a message to arrive and return it as a Message object.
+
+        Internally, it repeatedly polls GET /email/getmessage until the message arrives
+        or the overall timeout expires. Includes progress callback and cancellation support.
+
+        :param id: Activation ID.
+        :param timeout: Overall waiting limit in seconds.
+        :param poll_interval: Polling interval in seconds.
+        :param preview: Whether to use preview=1 mode.
+        :param on_tick: Optional progress callback: on_tick(iteration: int) -> None.
+        :param stop_event: Optional object with `is_set()` method to cancel waiting.
+        :return: Message
+        :raises WaitMessageError/ApiError/AuthError
+        """
+        from .methods.email import _wait_for_message
+        return _wait_for_message(
+            self.session,
+            self.token,
+            self.timeout,
+            id=id,
+            overall_timeout=timeout,        # corresponds to parameter name in the low-level function
+            poll_interval=poll_interval,
+            preview=preview,
+            on_tick=on_tick,
+            stop_event=stop_event,
+        )
+
+    def order_wait_and_extract(
+        self,
+        *,
+        site: str,
+        domain: Union[str, list],
+        regex: Optional[str] = None,
+        subject: Optional[str] = None,
+        timeout: Union[int, float] = 180,
+        poll_interval: Union[int, float] = 2.0,
+        preview: bool = False,
+        stop_event: Optional[object] = None,
+    ):
+        """
+        Convenience method: order an email → wait for message → extract via regex.
+
+        :return: Tuple (activation_id, email, html_or_text, extracted_value_or_None)
+        """
+        from .methods.email import order_wait_and_extract as _owe
+        return _owe(
+            self, site=site, domain=domain, regex=regex, subject=subject,
+            timeout=timeout, poll_interval=poll_interval, preview=preview,
+            stop_event=stop_event,
+        )
+
+    # ────────────────────────── Activation Rate ──────────────────────────
+
+    def get_ratio(self, *, full: bool = False):
+        """
+        Get activation rate statistics per site+domain pair.
+
+        Endpoint: GET /user/getratio
+        :param full: If True, include pairs with cancel_percent == 0 (ratio >= 40%).
+        :return: List[RatioEntry]
+        :raises AuthError: On authentication errors.
+        """
+        from .methods.ratio import _get_ratio
+        return _get_ratio(self.session, self.token, self.timeout, full=full)
+
+    def enable_block_ratio(self) -> bool:
+        """
+        Enable automatic blocking when activation rate drops below threshold.
+
+        Endpoint: GET /user/enableBlockRatio
+        :return: True on success.
+        """
+        from .methods.ratio import _enable_block_ratio
+        return _enable_block_ratio(self.session, self.token, self.timeout)
+
+    def disable_block_ratio(self) -> bool:
+        """
+        Disable automatic ratio blocking.
+
+        Endpoint: GET /user/disableBlockRatio
+        :return: True on success.
+        """
+        from .methods.ratio import _disable_block_ratio
+        return _disable_block_ratio(self.session, self.token, self.timeout)
+
+    # ────────────────────────── Long-live Emails ──────────────────────────
+
+    def get_longlive_quantity(self, *, site: str):
+        """
+        Get available long-term email domains and counts for a site.
+
+        Endpoint: GET /longlive-email/quantity
+        :param site: Target site (e.g., "instagram.com").
+        :return: QuantityResponse — data maps domain → {count, price}.
+        :raises ValidationError/AuthError
+        """
+        from .methods.longlive import _get_longlive_quantity
+        return _get_longlive_quantity(self.session, self.token, self.timeout, site=site)
+
+    def order_longlive_email(self, *, site: str, domain: str, count: int = 1):
+        """
+        Purchase one or more long-term mailboxes (bulk up to 1000).
+
+        Endpoint: GET /longlive-email/order
+        :param site: Target site (e.g., "instagram.com").
+        :param domain: Mailbox domain (e.g., "hotmail.com").
+        :param count: How many to buy (1–1000).
+        :return: LongliveOrderResponse
+        :raises ValidationError/NoEmailsError/NoBalanceError/AuthError
+        """
+        from .methods.longlive import _order_longlive_email
+        return _order_longlive_email(
+            self.session, self.token, self.timeout,
+            site=site, domain=domain, count=count,
+        )
+
+    def get_longlive_history(self, *, offset: int = 1, limit: int = 10) -> Dict[str, Any]:
+        """
+        Get long-term email order history.
+
+        Endpoint: GET /longlive-email/history
+        :param offset: Pagination offset (1-based).
+        :param limit: Number of records to return.
+        :return: Dict keyed by activation ID.
+        :raises AuthError
+        """
+        from .methods.longlive import _get_longlive_history
+        return _get_longlive_history(
+            self.session, self.token, self.timeout,
+            offset=offset, limit=limit,
+        )
+
+    def get_longlive_last_messages(
+        self,
+        *,
+        id: Union[str, int],
+        subject: Optional[str] = None,
+    ):
+        """
+        Get messages received in the last 40 minutes for a long-term activation.
+
+        Endpoint: GET /longlive-email/getlastmessages
+        :param id: Activation ID.
+        :param subject: Optional subject filter.
+        :return: List[LongliveMessage]
+        :raises ValidationError/NotFoundError/AuthError
+        """
+        from .methods.longlive import _get_longlive_last_messages
+        return _get_longlive_last_messages(
+            self.session, self.token, self.timeout,
+            id=id, subject=subject,
+        )
+
+    def get_longlive_messages(
+        self,
+        *,
+        id: Union[str, int],
+        created_at: Optional[int] = None,
+        subject: Optional[str] = None,
+    ):
+        """
+        Get all messages for a long-term activation.
+
+        Endpoint: GET /longlive-email/getmessages
+        :param id: Activation ID.
+        :param created_at: Optional Unix timestamp to return only newer messages.
+        :param subject: Optional subject filter.
+        :return: List[LongliveMessage]
+        :raises ValidationError/NotFoundError/AuthError
+        """
+        from .methods.longlive import _get_longlive_messages
+        return _get_longlive_messages(
+            self.session, self.token, self.timeout,
+            id=id, created_at=created_at, subject=subject,
+        )
+
+    def find_longlive_email(self, *, email: str) -> List[Dict[str, Any]]:
+        """
+        Find a previously purchased long-term mailbox by its email address.
+
+        Endpoint: GET /longlive-email/findemail
+        :param email: Full mailbox address (e.g., "example@outlook.com").
+        :return: List of activation records; empty list if not found.
+        :raises ValidationError/AuthError
+        """
+        from .methods.longlive import _find_longlive_email
+        return _find_longlive_email(self.session, self.token, self.timeout, email=email)

anymessage/config.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+config.py — basic configuration for the anymessage SDK
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Dict
+
+BASE_URL: str = "https://api.anymessage.shop"
+DEFAULT_TIMEOUT: int = 30
+
+@dataclass(frozen=True)
+class SDKInfo:
+    name: str = "anymessage-python"
+    version: str = "0.2.0"
+
+SDK_INFO = SDKInfo()
+
+def get_soft_header() -> Dict[str, str]:
+    return {
+        "X-Soft-Id": "126",
+        "X-SDK-Name": SDK_INFO.name,
+        "X-SDK-Version": SDK_INFO.version,
+    }
+
+DEBUG_HTTP: bool = True

anymessage/errors.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""
+errors.py — exception definitions for the anymessage SDK
+
+All client exceptions inherit from the base class AnyMessageError.
+Each specific error corresponds to a particular API error value,
+for example: {"status":"error","value":"token"} → AuthError.
+"""
+
+
+class AnyMessageError(Exception):
+    """Base exception for all SDK errors."""
+
+
+# --- Authorization / Parameter Errors ----------------------------------------
+
+class AuthError(AnyMessageError):
+    """Invalid or missing API token."""
+
+
+class ValidationError(AnyMessageError):
+    """Invalid or missing parameter (e.g., site, domain)."""
+
+
+# --- Activation-related Errors ----------------------------------------------
+
+class NotFoundError(AnyMessageError):
+    """Activation or resource not found."""
+
+
+class NoBalanceError(AnyMessageError):
+    """Insufficient balance."""
+
+
+class NoEmailsError(AnyMessageError):
+    """No available emails for the given site or domain."""
+
+
+class ActivationCanceledError(AnyMessageError):
+    """Activation has been canceled by the user."""
+
+
+class ActivationAlreadyCanceledError(AnyMessageError):
+    """Activation has already been canceled."""
+
+
+class EmailBannedError(AnyMessageError):
+    """This email address is banned by the service."""
+
+
+class RatioBlockError(AnyMessageError):
+    """Blocked due to low activation rate for this site+domain pair."""
+
+
+# --- Message Waiting --------------------------------------------------------
+
+class WaitMessageError(AnyMessageError):
+    """Message not yet available (API returned 'wait message')."""
+
+
+# --- Mapping API 'value' field to exceptions --------------------------------
+
+ERROR_VALUE_TO_EXCEPTION = {
+    "token": AuthError,
+    "site": ValidationError,
+    "domain": ValidationError,
+    "no activation": NotFoundError,
+    "activation canceled": ActivationCanceledError,
+    "activation already canceled": ActivationAlreadyCanceledError,
+    "no balance": NoBalanceError,
+    "no emails": NoEmailsError,
+    "email banned": EmailBannedError,
+    "wait message": WaitMessageError,
+    "ratio block": RatioBlockError,
+}
+
+
+def map_api_error(value: str) -> AnyMessageError:
+    """
+    Map the API "value" field to a corresponding exception class.
+
+    Example:
+        >>> map_api_error("token")
+        AuthError('token')
+
+    :param value: String value from the API response field "value".
+    :return: Instance of the corresponding exception.
+    """
+    exc_cls = ERROR_VALUE_TO_EXCEPTION.get(value, AnyMessageError)
+    return exc_cls(value)