bridgexapi 0.1.0__tar.gz

bridgexapi-0.1.0/LICENSE

@@ -0,0 +1 @@
+Copyright (c) BridgeXAPI. All rights reserved.

bridgexapi-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: bridgexapi
+Version: 0.1.0
+Summary: Official Python SDK for the BridgeXAPI SMS API
+Author: BridgeXAPI
+Project-URL: Homepage, https://dashboard.bridgexapi.io
+Project-URL: Documentation, https://dashboard.bridgexapi.io
+Project-URL: Source, https://dashboard.bridgexapi.io
+Keywords: sms,api,messaging,bridgexapi,python-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# BridgeXAPI Python SDK
+
+Official Python SDK for the BridgeXAPI SMS API.
+
+The BridgeXAPI Python SDK provides a simple and secure way to send SMS through the BridgeXAPI infrastructure using one API key, one endpoint, and route-based delivery selection.
+
+## Features
+
+- Official Python SDK for BridgeXAPI SMS
+- Simple sync client
+- Local validation before requests are sent
+- Support for route IDs `1` through `5`
+- Typed route constants via `Route`
+- Structured response models
+- Clean Python exceptions
+- Server-side integration ready
+
+## Installation
+
+### Local development
+
+```bash
+pip install -e .

bridgexapi-0.1.0/README.md

@@ -0,0 +1,23 @@
+# BridgeXAPI Python SDK
+
+Official Python SDK for the BridgeXAPI SMS API.
+
+The BridgeXAPI Python SDK provides a simple and secure way to send SMS through the BridgeXAPI infrastructure using one API key, one endpoint, and route-based delivery selection.
+
+## Features
+
+- Official Python SDK for BridgeXAPI SMS
+- Simple sync client
+- Local validation before requests are sent
+- Support for route IDs `1` through `5`
+- Typed route constants via `Route`
+- Structured response models
+- Clean Python exceptions
+- Server-side integration ready
+
+## Installation
+
+### Local development
+
+```bash
+pip install -e .

bridgexapi-0.1.0/bridgexapi/__init__.py

@@ -0,0 +1,40 @@
+from .client import BridgeXAPI
+from .version import __version__
+from .routes import Route
+from .models import SMSBatchResponse, SMSMessageStatus
+from .exceptions import (
+    BridgeXAPIError,
+    ApiRequestError,
+    AuthenticationError,
+    ValidationError,
+    InvalidRouteError,
+    UnauthorizedRouteError,
+    InsufficientBalanceError,
+    VendorSendError,
+    InvalidNumberError,
+    MixedCountryBatchError,
+    MessageTooLongError,
+    UnicodeNotAllowedError,
+    InvalidCallerIDError,
+)
+
+__all__ = [
+    "BridgeXAPI",
+    "__version__",
+    "Route",
+    "SMSBatchResponse",
+    "SMSMessageStatus",
+    "BridgeXAPIError",
+    "ApiRequestError",
+    "AuthenticationError",
+    "ValidationError",
+    "InvalidRouteError",
+    "UnauthorizedRouteError",
+    "InsufficientBalanceError",
+    "VendorSendError",
+    "InvalidNumberError",
+    "MixedCountryBatchError",
+    "MessageTooLongError",
+    "UnicodeNotAllowedError",
+    "InvalidCallerIDError",
+]

bridgexapi-0.1.0/bridgexapi/client.py

@@ -0,0 +1,133 @@
+from typing import Iterable, Optional, Any
+
+import requests
+
+from .exceptions import (
+    ApiRequestError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    InvalidRouteError,
+    UnauthorizedRouteError,
+    ValidationError,
+    VendorSendError,
+)
+from .models import SMSBatchResponse
+from .validators import (
+    validate_route_id,
+    validate_caller_id,
+    validate_numbers,
+    validate_message,
+)
+
+
+class BridgeXAPI:
+    """
+    Official sync client for the BridgeXAPI SMS endpoint.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://hi.bridgexapi.io",
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise AuthenticationError("api_key is required.")
+
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    @property
+    def endpoint(self) -> str:
+        return f"{self.base_url}/api/v1/send_sms"
+
+    def send_sms(
+        self,
+        *,
+        route_id: int,
+        caller_id: str,
+        numbers: Iterable[str],
+        message: str,
+    ) -> SMSBatchResponse:
+        payload = {
+            "route_id": validate_route_id(route_id),
+            "caller_id": validate_caller_id(caller_id),
+            "numbers": validate_numbers(numbers),
+            "message": validate_message(message),
+        }
+
+        response = self.session.post(
+            self.endpoint,
+            headers={
+                "Content-Type": "application/json",
+                "X-API-KEY": self.api_key,
+            },
+            json=payload,
+            timeout=self.timeout,
+        )
+
+        data = self._decode_json(response)
+        self._raise_for_error(response.status_code, data)
+
+        return SMSBatchResponse.from_dict(data)
+
+    def send_one(
+        self,
+        *,
+        route_id: int,
+        caller_id: str,
+        number: str,
+        message: str,
+    ) -> SMSBatchResponse:
+        return self.send_sms(
+            route_id=route_id,
+            caller_id=caller_id,
+            numbers=[number],
+            message=message,
+        )
+
+    def _decode_json(self, response: requests.Response) -> dict[str, Any]:
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ApiRequestError(
+                f"BridgeXAPI returned a non-JSON response (status {response.status_code})."
+            ) from exc
+
+    def _raise_for_error(self, status_code: int, data: dict[str, Any]) -> None:
+        if 200 <= status_code < 300:
+            return
+
+        detail = data.get("detail")
+
+        if isinstance(detail, list):
+            first = detail[0] if detail else {}
+            msg = first.get("msg") or "Validation error."
+            raise ValidationError(msg)
+
+        if isinstance(detail, str):
+            if "Missing API Key" in detail or "Invalid or inactive API Key" in detail:
+                raise AuthenticationError(detail)
+
+            if "Invalid route_id" in detail:
+                raise InvalidRouteError(detail)
+
+            if "not authorized for the Casino route" in detail:
+                raise UnauthorizedRouteError(detail)
+
+            if "Insufficient balance" in detail:
+                raise InsufficientBalanceError(detail)
+
+            if "Vendor send failed" in detail:
+                raise VendorSendError(detail)
+
+            if "Pricing failed" in detail:
+                raise ValidationError(detail)
+
+            raise ApiRequestError(detail)
+
+        raise ApiRequestError(f"BridgeXAPI request failed with status {status_code}.")

bridgexapi-0.1.0/bridgexapi/exceptions.py

@@ -0,0 +1,50 @@
+class BridgeXAPIError(Exception):
+    """Base exception for all BridgeXAPI SDK errors."""
+
+
+class ApiRequestError(BridgeXAPIError):
+    """Generic API request error."""
+
+
+class AuthenticationError(ApiRequestError):
+    """Missing, invalid, or inactive API key."""
+
+
+class ValidationError(ApiRequestError):
+    """Payload validation failed."""
+
+
+class InvalidRouteError(ValidationError):
+    """Invalid route_id supplied."""
+
+
+class UnauthorizedRouteError(ApiRequestError):
+    """User is not allowed to use the selected route."""
+
+
+class InsufficientBalanceError(ApiRequestError):
+    """User balance is too low for this request."""
+
+
+class VendorSendError(ApiRequestError):
+    """Vendor gateway failed to accept the SMS request."""
+
+
+class InvalidNumberError(ValidationError):
+    """Phone number format is invalid."""
+
+
+class MixedCountryBatchError(ValidationError):
+    """Numbers from multiple countries were provided in one request."""
+
+
+class MessageTooLongError(ValidationError):
+    """Message exceeds the maximum allowed length."""
+
+
+class UnicodeNotAllowedError(ValidationError):
+    """Message contains non-ASCII characters."""
+
+
+class InvalidCallerIDError(ValidationError):
+    """Caller ID is invalid."""

bridgexapi-0.1.0/bridgexapi/models.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass, asdict
+from typing import Optional, List, Any
+
+
+@dataclass(slots=True)
+class SMSMessageStatus:
+    bx_message_id: Optional[str]
+    msisdn: str
+    status: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SMSMessageStatus":
+        return cls(
+            bx_message_id=data.get("bx_message_id"),
+            msisdn=str(data.get("msisdn", "")),
+            status=str(data.get("status", "")),
+        )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class SMSBatchResponse:
+    status: str
+    message: str
+    order_id: Optional[int]
+    route_id: int
+    count: int
+    messages: List[SMSMessageStatus]
+    cost: Optional[float]
+    balance_after: Optional[float]
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SMSBatchResponse":
+        return cls(
+            status=str(data.get("status", "")),
+            message=str(data.get("message", "")),
+            order_id=data.get("order_id"),
+            route_id=int(data.get("route_id", 0)),
+            count=int(data.get("count", 0)),
+            messages=[SMSMessageStatus.from_dict(x) for x in data.get("messages", [])],
+            cost=float(data["cost"]) if data.get("cost") is not None else None,
+            balance_after=float(data["balance_after"]) if data.get("balance_after") is not None else None,
+            raw=data,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "message": self.message,
+            "order_id": self.order_id,
+            "route_id": self.route_id,
+            "count": self.count,
+            "messages": [m.to_dict() for m in self.messages],
+            "cost": self.cost,
+            "balance_after": self.balance_after,
+            "raw": self.raw,
+        }

bridgexapi-0.1.0/bridgexapi/routes.py

@@ -0,0 +1,19 @@
+from enum import IntEnum
+
+
+class Route(IntEnum):
+    """
+    BridgeXAPI route identifiers.
+
+    Each route represents a different SMS delivery path.
+    Route 1 is typically the primary route, while routes 2–4
+    are backup or alternative routes depending on availability.
+
+    Route 5 is restricted to authorized iGaming clients.
+    """
+
+    ROUTE_1 = 1
+    ROUTE_2 = 2
+    ROUTE_3 = 3
+    ROUTE_4 = 4
+    CASINO = 5

bridgexapi-0.1.0/bridgexapi/validators.py

@@ -0,0 +1,102 @@
+import re
+from typing import Iterable, List
+
+from .exceptions import (
+    InvalidCallerIDError,
+    InvalidNumberError,
+    InvalidRouteError,
+    MessageTooLongError,
+    MixedCountryBatchError,
+    UnicodeNotAllowedError,
+)
+
+VALID_ROUTES = {1, 2, 3, 4, 5}
+NUMBER_RE = re.compile(r"^\d{10,15}$")
+
+
+def normalize_number(number: str) -> str:
+    """
+    Normalize user input into BridgeXAPI format.
+    Removes spaces, dashes, parentheses and other non-digits.
+    """
+    if not isinstance(number, str):
+        raise InvalidNumberError("Phone number must be a string.")
+    return re.sub(r"\D", "", number.strip())
+
+
+def validate_route_id(route_id: int) -> int:
+    if route_id not in VALID_ROUTES:
+        raise InvalidRouteError("route_id must be between 1 and 5.")
+    return route_id
+
+
+def validate_caller_id(caller_id: str) -> str:
+    if not isinstance(caller_id, str):
+        raise InvalidCallerIDError("caller_id must be a string.")
+
+    caller_id = caller_id.strip()
+
+    if not (3 <= len(caller_id) <= 11):
+        raise InvalidCallerIDError("caller_id must be between 3 and 11 characters.")
+
+    return caller_id
+
+
+def validate_message(message: str) -> str:
+    if not isinstance(message, str):
+        raise MessageTooLongError("message must be a string.")
+
+    if len(message) > 158:
+        raise MessageTooLongError("Message must contain at most 158 characters.")
+
+    if not message.isascii():
+        raise UnicodeNotAllowedError("Message must contain only ASCII characters.")
+
+    return message
+
+
+def validate_numbers(numbers: Iterable[str]) -> List[str]:
+    numbers = list(numbers)
+
+    if not numbers:
+        raise InvalidNumberError("numbers must contain at least one phone number.")
+
+    normalized = []
+
+    for raw in numbers:
+        if not isinstance(raw, str):
+            raise InvalidNumberError("Each number must be a string.")
+
+        if raw.strip().startswith("+"):
+            raise InvalidNumberError("Number must not start with '+'.")
+
+        cleaned = normalize_number(raw)
+
+        if not NUMBER_RE.fullmatch(cleaned):
+            raise InvalidNumberError("Each number must be 10 to 15 digits, digits only.")
+
+        normalized.append(cleaned)
+
+    validate_same_country(normalized)
+    return normalized
+
+
+def validate_same_country(numbers: List[str]) -> None:
+    """
+    BridgeXAPI business rule:
+    all numbers in one request must belong to the same country.
+
+    Current SDK heuristic:
+    compare first 3, 2 or 1 digits against the first number.
+    """
+    if len(numbers) <= 1:
+        return
+
+    ref3, ref2, ref1 = numbers[0][:3], numbers[0][:2], numbers[0][:1]
+
+    for number in numbers[1:]:
+        cur3, cur2, cur1 = number[:3], number[:2], number[:1]
+        if not (cur3 == ref3 or cur2 == ref2 or cur1 == ref1):
+            raise MixedCountryBatchError(
+                "All numbers in one request must belong to the same country."
+            )

bridgexapi-0.1.0/bridgexapi/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bridgexapi-0.1.0/bridgexapi.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: bridgexapi
+Version: 0.1.0
+Summary: Official Python SDK for the BridgeXAPI SMS API
+Author: BridgeXAPI
+Project-URL: Homepage, https://dashboard.bridgexapi.io
+Project-URL: Documentation, https://dashboard.bridgexapi.io
+Project-URL: Source, https://dashboard.bridgexapi.io
+Keywords: sms,api,messaging,bridgexapi,python-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# BridgeXAPI Python SDK
+
+Official Python SDK for the BridgeXAPI SMS API.
+
+The BridgeXAPI Python SDK provides a simple and secure way to send SMS through the BridgeXAPI infrastructure using one API key, one endpoint, and route-based delivery selection.
+
+## Features
+
+- Official Python SDK for BridgeXAPI SMS
+- Simple sync client
+- Local validation before requests are sent
+- Support for route IDs `1` through `5`
+- Typed route constants via `Route`
+- Structured response models
+- Clean Python exceptions
+- Server-side integration ready
+
+## Installation
+
+### Local development
+
+```bash
+pip install -e .

bridgexapi-0.1.0/bridgexapi.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+bridgexapi/__init__.py
+bridgexapi/client.py
+bridgexapi/exceptions.py
+bridgexapi/models.py
+bridgexapi/routes.py
+bridgexapi/validators.py
+bridgexapi/version.py
+bridgexapi.egg-info/PKG-INFO
+bridgexapi.egg-info/SOURCES.txt
+bridgexapi.egg-info/dependency_links.txt
+bridgexapi.egg-info/requires.txt
+bridgexapi.egg-info/top_level.txt

bridgexapi-0.1.0/bridgexapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bridgexapi-0.1.0/bridgexapi.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

bridgexapi-0.1.0/bridgexapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+bridgexapi

bridgexapi-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bridgexapi"
+version = "0.1.0"
+description = "Official Python SDK for the BridgeXAPI SMS API"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "BridgeXAPI" }
+]
+dependencies = [
+  "requests>=2.31.0"
+]
+keywords = ["sms", "api", "messaging", "bridgexapi", "python-sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Communications",
+  "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://dashboard.bridgexapi.io"
+Documentation = "https://dashboard.bridgexapi.io"
+Source = "https://dashboard.bridgexapi.io"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["bridgexapi*"]

bridgexapi-0.1.0/setup.cfg

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