textverified 0.1.0a0__py3-none-any.whl

textverified/__init__.py

@@ -0,0 +1,288 @@
+"""
+TextVerified Python Client
+
+This package provides a Python interface to the TextVerified API.
+You can either use the TextVerified class directly to manage multiple credentials
+or access API endpoints statically.
+
+Example usage:
+    from textverified import services, verifications
+    # or
+    from textverified import TextVerified
+    client = TextVerified(api_key="...", api_username="...")
+"""
+
+import os
+import sys
+from typing import Optional
+
+# Import the main TextVerified class and API modules
+from .textverified import TextVerified, BearerToken
+from .account_api import AccountAPI
+from .billing_cycle_api import BillingCycleAPI
+from .reservations_api import ReservationsAPI
+from .sales_api import SalesAPI
+from .services_api import ServicesAPI
+from .sms_api import SMSApi
+from .verifications_api import VerificationsAPI
+from .wake_api import WakeAPI
+from .paginated_list import PaginatedList
+from .exceptions import TextVerifiedError
+
+# Import generated enums
+from .data import *
+
+# Configurable, lazy-initialized static instance
+_static_instance: Optional[TextVerified] = None
+
+
+def _get_static_instance() -> TextVerified:
+    """Get or create the static TextVerified instance."""
+    global _static_instance
+    if _static_instance is None:
+        api_key = os.environ.get("TEXTVERIFIED_API_KEY")
+        api_username = os.environ.get("TEXTVERIFIED_API_USERNAME")
+        base_url = os.environ.get("TEXTVERIFIED_BASE_URL", "https://www.textverified.com")
+        user_agent = os.environ.get("TEXTVERIFIED_USER_AGENT", "TextVerified-Python-Client/0.1.0")
+
+        if not api_key or not api_username:
+            raise ValueError(
+                "TextVerified static instance not configured. "
+                "Either call configure() or set TEXTVERIFIED_API_KEY and TEXTVERIFIED_API_USERNAME environment variables."
+            )
+
+        _static_instance = TextVerified(
+            api_key=api_key, api_username=api_username, base_url=base_url, user_agent=user_agent
+        )
+
+    return _static_instance
+
+
+def configure(
+    api_key: str,
+    api_username: str,
+    base_url: str = "https://www.textverified.com",
+    user_agent: str = "TextVerified-Python-Client/0.1.0",
+) -> None:
+    """Configure the static TextVerified instance."""
+    global _static_instance
+    _static_instance = TextVerified(
+        api_key=api_key, api_username=api_username, base_url=base_url, user_agent=user_agent
+    )
+
+
+# Lazy property implementation using __getattr__ at module level
+class _LazyAPI:
+    """
+    Lazy wrapper for API endpoints that creates the static TextVerified instance
+    only when an API endpoint is actually accessed.
+    """
+
+    def __init__(self, attr_name: str, doc: str = None):
+        self.attr_name = attr_name
+        if doc:
+            self.__doc__ = doc
+
+    def __getattr__(self, name):
+        """Forward attribute access to the actual API endpoint."""
+        api_endpoint = getattr(_get_static_instance(), self.attr_name)
+        return getattr(api_endpoint, name)
+
+    def __call__(self, *args, **kwargs):
+        """Forward method calls to the actual API endpoint."""
+        api_endpoint = getattr(_get_static_instance(), self.attr_name)
+        return api_endpoint(*args, **kwargs)
+
+
+# Create lazy API wrappers with documentation
+account = _LazyAPI(
+    "account",
+    """
+Static access to account management functionality.
+
+Provides methods for retrieving account information, balance, and account settings.
+This is a static wrapper around the AccountAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import account
+    
+    # Get account information
+    account_info = account.me()
+    
+    # Get account balance
+    balance = account.balance()
+""",
+)
+
+billing_cycles = _LazyAPI(
+    "billing_cycles",
+    """
+Static access to billing cycle management functionality.
+
+Provides methods for managing billing cycles, invoices, and payment history.
+This is a static wrapper around the BillingCycleAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import billing_cycles
+    
+    # List all billing cycles
+    cycles = billing_cycles.list()
+    
+    # Get specific billing cycle
+    cycle = billing_cycles.get(cycle_id)
+""",
+)
+
+reservations = _LazyAPI(
+    "reservations",
+    """
+Static access to phone number reservation functionality.
+
+Provides methods for creating, managing, and releasing phone number reservations.
+This is a static wrapper around the ReservationsAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import reservations
+    
+    # Create a new reservation
+    reservation = reservations.create(service_id=1, area_code="555")
+    
+    # List all reservations
+    all_reservations = reservations.list()
+""",
+)
+
+sales = _LazyAPI(
+    "sales",
+    """
+Static access to sales and transaction functionality.
+
+Provides methods for retrieving sales history, transaction details, and revenue analytics.
+This is a static wrapper around the SalesAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import sales
+    
+    # Get sales history
+    sales_history = sales.list()
+    
+    # Get specific sale details
+    sale = sales.get(sale_id)
+""",
+)
+
+services = _LazyAPI(
+    "services",
+    """
+Static access to service management functionality.
+
+Provides methods for listing available services, getting service pricing,
+and retrieving service-specific information.
+This is a static wrapper around the ServicesAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import services
+    
+    # Get all available services
+    available_services = services.list()
+    
+    # Get pricing for rentals
+    pricing = services.pricing_rentals()
+""",
+)
+
+verifications = _LazyAPI(
+    "verifications",
+    """
+Static access to phone verification functionality.
+
+Provides methods for creating verification requests, checking verification status,
+and managing the verification process.
+This is a static wrapper around the VerificationsAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import verifications
+    
+    # Create a new verification
+    verification = verifications.create(service_id=1)
+    
+    # Check verification status
+    status = verifications.get(verification_id)
+""",
+)
+
+wake_requests = _LazyAPI(
+    "wake_requests",
+    """
+Static access to wake request functionality.
+
+Provides methods for creating and managing wake requests for phone numbers.
+This is a static wrapper around the WakeAPI class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import wake_requests
+    
+    # Create a wake request
+    wake = wake_requests.create(phone_number="+1234567890")
+    
+    # List wake requests
+    wakes = wake_requests.list()
+""",
+)
+
+sms = _LazyAPI(
+    "sms",
+    """
+Static access to SMS management functionality.
+
+Provides methods for sending, receiving, and managing SMS messages.
+This is a static wrapper around the SMSApi class that uses the globally
+configured TextVerified instance.
+
+Example:
+    from textverified import sms
+    
+    # Get SMS messages
+    messages = sms.list()
+    
+    # Get specific SMS
+    message = sms.get(message_id)
+""",
+)
+
+
+# Available for import:
+__all__ = [
+    # Main classes
+    "TextVerified",
+    "BearerToken",
+    "PaginatedList",
+    "TextVerifiedError",
+    # Configuration
+    "configure",
+    # Static API access
+    "account",
+    "billing_cycles",
+    "reservations",
+    "sales",
+    "services",
+    "verifications",
+    "wake_requests",
+    "sms",
+    # API classes (for direct instantiation if needed)
+    "AccountAPI",
+    "BillingCycleAPI",
+    "ReservationsAPI",
+    "SalesAPI",
+    "ServicesAPI",
+    "SMSApi",
+    "VerificationsAPI",
+    "WakeAPI",
+] + data.__all__

textverified/account_api.py

@@ -0,0 +1,32 @@
+from .action import _Action, _ActionPerformer
+from dataclasses import dataclass
+from .data import Account
+
+
+class AccountAPI:
+    """API endpoints related to account management."""
+
+    def __init__(self, client: _ActionPerformer):
+        self.client = client
+
+    def me(self) -> Account:
+        """
+        Returns:
+            Account: The current account details.
+        """
+        action = _Action(method="GET", href="/api/pub/v2/account/me")
+        response = self.client._perform_action(action)
+        return Account.from_api(response.data)
+
+    @property
+    def balance(self) -> float:
+        """Get the current account balance."""
+        details = self.me()
+        return details.current_balance
+
+    @property
+    def username(self) -> str:
+        """Get the current account username."""
+        # Realistically, this is the only request we could cache
+        details = self.me()
+        return details.username

textverified/action.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Union
+from requests.structures import CaseInsensitiveDict
+
+
+@dataclass(frozen=True)
+class _ActionResponse:
+    """Internal Protocol for API responses."""
+
+    data: Any
+    headers: "CaseInsensitiveDict[str, Union[str, int]]"
+
+
+class _ActionPerformer:
+    """Internal Protocol for objects that can perform API actions."""
+
+    def _perform_action(self, action: "_Action", **kwargs) -> _ActionResponse:
+        """
+        Perform an API action and return the result.
+        :param action: The action to perform
+        :return: Dictionary containing the API response
+        """
+        pass
+
+
+@dataclass(frozen=True)
+class _Action:
+    """Single API action. Often returned by the API but also used internally."""
+
+    method: str
+    href: str
+
+    def to_api(self) -> dict:
+        """
+        Convert the Action instance to an API-compatible dictionary.
+        :return: Dictionary representation of the Action for API requests.
+        """
+        return {"method": self.method, "href": self.href}
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "_Action":
+        """
+        Create an Action instance from API data.
+        :param data: Dictionary containing the API data.
+        :return: Action instance.
+        """
+        return cls(method=data["method"], href=data["href"])

textverified/billing_cycle_api.py

@@ -0,0 +1,178 @@
+from .action import _ActionPerformer, _Action
+from typing import List, Union
+from .data import (
+    BillingCycleCompact,
+    BillingCycleExpanded,
+    BillingCycleUpdateRequest,
+    BillingCycleRenewalInvoicePreview,
+    BillingCycleRenewalInvoice,
+)
+from .paginated_list import PaginatedList
+
+
+class BillingCycleAPI:
+    """API endpoints related to billing cycles.
+    Renewable rentals are associated with billing cycles and can be manually assigned on rental creation or automatically assigned.
+    A single billing cycle can have multiple renewable rentals.
+    Billing cycles can be updated, renewed, and queried for invoices."""
+
+    def __init__(self, client: _ActionPerformer):
+        self.client = client
+
+    def list(self) -> PaginatedList[BillingCycleCompact]:
+        """Fetch all billing cycles associated with this account."""
+        action = _Action(method="GET", href="/api/pub/v2/billing-cycles")
+        response = self.client._perform_action(action)
+
+        return PaginatedList(
+            request_json=response.data, parse_item=BillingCycleCompact.from_api, api_context=self.client
+        )
+
+    def get(self, billing_cycle_id: str) -> BillingCycleExpanded:
+        """Get the details of a billing cycle by ID.
+
+        Args:
+            billing_cycle_id (str): The ID of the billing cycle to retrieve.
+
+        Returns:
+            BillingCycleExpanded: The detailed information about the billing cycle.
+        """
+        action = _Action(method="GET", href=f"/api/pub/v2/billing-cycles/{billing_cycle_id}")
+        response = self.client._perform_action(action)
+
+        return BillingCycleExpanded.from_api(response.data)
+
+    def update(
+        self,
+        billing_cycle: Union[str, BillingCycleCompact, BillingCycleExpanded],
+        data: BillingCycleUpdateRequest = None,
+        *,
+        reminders_enabled: bool = None,
+        nickname: str = None,
+    ) -> bool:
+        """Update a billing cycle.
+
+        Args:
+            billing_cycle (Union[str, BillingCycleCompact, BillingCycleExpanded]): The ID or instance of the billing cycle to update.
+            data (BillingCycleUpdateRequest, optional): Data to update. Overwritten by kwargs. Defaults to None.
+            reminders_enabled (bool, optional): Whether email reminders are enabled. Defaults to None.
+            nickname (str, optional): Your custom string to identify the billing cycle. Defaults to None.
+
+        Raises:
+            ValueError: If billing_cycle is not a valid ID or instance, or if no fields are provided to update.
+
+        Returns:
+            bool: True if the update was successful, False otherwise.
+        """
+        billing_cycle_id = (
+            billing_cycle.id
+            if isinstance(billing_cycle, (BillingCycleCompact, BillingCycleExpanded))
+            else billing_cycle
+        )
+
+        update_request = (
+            BillingCycleUpdateRequest(
+                reminders_enabled=reminders_enabled if reminders_enabled is not None else data.reminders_enabled,
+                nickname=nickname or data.nickname,
+            )
+            if data
+            else BillingCycleUpdateRequest(reminders_enabled=reminders_enabled, nickname=nickname)
+        )
+
+        if not billing_cycle_id or not isinstance(billing_cycle_id, str):
+            raise ValueError("billing_cycle must be a valid ID or instance of BillingCycleCompact/Expanded.")
+
+        if not update_request or (not update_request.reminders_enabled and not update_request.nickname):
+            raise ValueError("At least one field must be updated: reminders_enabled or nickname.")
+
+        action = _Action(method="POST", href=f"/api/pub/v2/billing-cycles/{billing_cycle_id}")
+        response = self.client._perform_action(action, json=update_request.to_api())
+
+        return True
+
+    def invoices(
+        self, billing_cycle_id: Union[str, BillingCycleCompact, BillingCycleExpanded]
+    ) -> PaginatedList[BillingCycleRenewalInvoice]:
+        """Get invoices for a specific billing cycle.
+
+        Args:
+            billing_cycle_id (Union[str, BillingCycleCompact, BillingCycleExpanded]): The ID or instance of the billing cycle to retrieve invoices for.
+
+        Raises:
+            ValueError: If billing_cycle_id is not a valid ID or instance.
+
+        Returns:
+            PaginatedList[BillingCycleRenewalInvoice]: A paginated list of billing cycle renewal invoices.
+        """
+
+        billing_cycle_id = (
+            billing_cycle_id.id
+            if isinstance(billing_cycle_id, (BillingCycleCompact, BillingCycleExpanded))
+            else billing_cycle_id
+        )
+
+        if not billing_cycle_id or not isinstance(billing_cycle_id, str):
+            raise ValueError("billing_cycle_id must be a valid ID or instance of BillingCycleCompact/Expanded.")
+
+        action = _Action(method="GET", href=f"/api/pub/v2/billing-cycles/{billing_cycle_id}/invoices")
+        response = self.client._perform_action(action)
+
+        return PaginatedList(
+            request_json=response.data, parse_item=BillingCycleRenewalInvoice.from_api, api_context=self.client
+        )
+
+    def preview(
+        self, billing_cycle_id: Union[str, BillingCycleCompact, BillingCycleExpanded]
+    ) -> BillingCycleRenewalInvoice:
+        """Preview the next billing cycle invoice.
+
+        Args:
+            billing_cycle_id (Union[str, BillingCycleCompact, BillingCycleExpanded]): The ID or instance of the billing cycle to preview.
+
+        Raises:
+            ValueError: If billing_cycle_id is not a valid ID or instance.
+
+        Returns:
+            BillingCycleRenewalInvoice: The preview of the next billing cycle invoice.
+        """
+
+        billing_cycle_id = (
+            billing_cycle_id.id
+            if isinstance(billing_cycle_id, (BillingCycleCompact, BillingCycleExpanded))
+            else billing_cycle_id
+        )
+
+        if not billing_cycle_id or not isinstance(billing_cycle_id, str):
+            raise ValueError("billing_cycle_id must be a valid ID or instance of BillingCycleCompact/Expanded.")
+
+        action = _Action(method="POST", href=f"/api/pub/v2/billing-cycles/{billing_cycle_id}/next-invoice")
+        response = self.client._perform_action(action)
+        return BillingCycleRenewalInvoicePreview.from_api(response.data)
+
+    def renew(self, billing_cycle_id: Union[str, BillingCycleCompact, BillingCycleExpanded]) -> bool:
+        """Renew the active rentals on your billing cycle.
+        Will not renew overdue rentals. To renew overdue rentals, you must explicitly call `textverified.reservations.renew_overdue_renewable_reservation` on each overdue rental.
+
+        Args:
+            billing_cycle_id (Union[str, BillingCycleCompact, BillingCycleExpanded]): The ID or instance of the billing cycle to renew.
+
+        Raises:
+            ValueError: If billing_cycle_id is not a valid ID or instance.
+
+        Returns:
+            bool: True if the billing cycle was renewed successfully, False otherwise.
+        """
+
+        billing_cycle_id = (
+            billing_cycle_id.id
+            if isinstance(billing_cycle_id, (BillingCycleCompact, BillingCycleExpanded))
+            else billing_cycle_id
+        )
+
+        if not billing_cycle_id or not isinstance(billing_cycle_id, str):
+            raise ValueError("billing_cycle_id must be a valid ID or instance of BillingCycleCompact/Expanded.")
+
+        action = _Action(method="POST", href=f"/api/pub/v2/billing-cycles/{billing_cycle_id}/renew")
+        self.client._perform_action(action)
+
+        return True

textverified/data/__init__.py

@@ -0,0 +1,9 @@
+import inspect
+from . import dtypes
+from .dtypes import *
+
+__all__ = [
+    name
+    for name, obj in inspect.getmembers(dtypes, inspect.isclass)
+    if obj.__module__ == dtypes.__name__ and not name.startswith("_")
+]