verixo 0.1.0__tar.gz

verixo-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/

verixo-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: verixo
+Version: 0.1.0
+Summary: Official Python SDK for the Verixo OTP-as-a-Service API
+Project-URL: Homepage, https://verifiedcore.com
+Project-URL: Repository, https://github.com/titicodes/verixo
+License-Expression: MIT
+Keywords: otp,phone-verification,sms-verification,verixo
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.27
+Requires-Dist: websocket-client>=1.6
+Description-Content-Type: text/markdown
+
+# verixo
+
+Official Python SDK for the [Verixo](https://verifiedcore.com) OTP-as-a-Service API.
+
+## Install
+
+```bash
+pip install verixo
+```
+
+## Quickstart
+
+```python
+import os
+import verixo
+
+client = verixo.Client(os.environ["VC_API_KEY"])
+
+result = client.numbers.search(
+    service_slug="whatsapp",
+    country_code="NG",
+    min_score=80,
+    limit=5,
+)
+
+session = client.numbers.purchase(
+    service_slug="whatsapp",
+    country_code="NG",
+)
+
+def handle(push):
+    print(f"OTP: {push.otp} in {push.latency_ms}ms")
+
+client.subscribe(session.session_token, handle)
+```
+
+Note: `purchase()` takes `service_slug` + `country_code`, not a specific
+`number_id` -- the server picks the best available number by Health Score at
+purchase time, since a candidate returned by `search()` may already be gone
+by the time you'd reference it back.
+
+## Polling instead of real-time push
+
+`subscribe()` runs a background thread holding a persistent WebSocket
+connection, which isn't always practical (e.g. one-shot scripts, serverless
+functions). Use `sessions.wait_for_otp()` instead:
+
+```python
+result = client.sessions.wait_for_otp(session.session_token)
+if result.status == "DELIVERED":
+    print(result.otp_code)
+```
+
+## Errors
+
+All non-2xx responses raise `verixo.VerixoError` with `.status`, and usually
+`.code`/`.detail` from the API's error body:
+
+```python
+from verixo import VerixoError
+
+try:
+    client.numbers.purchase(service_slug="whatsapp", country_code="NG")
+except VerixoError as err:
+    if err.status == 402:
+        print("Insufficient wallet balance")
+```
+
+## Requirements
+
+Python 3.8+.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate   # or `source .venv/bin/activate` on macOS/Linux
+pip install -e .
+python examples/quickstart.py   # requires VC_API_KEY env var, see file header
+```

verixo-0.1.0/README.md

@@ -0,0 +1,80 @@
+# verixo
+
+Official Python SDK for the [Verixo](https://verifiedcore.com) OTP-as-a-Service API.
+
+## Install
+
+```bash
+pip install verixo
+```
+
+## Quickstart
+
+```python
+import os
+import verixo
+
+client = verixo.Client(os.environ["VC_API_KEY"])
+
+result = client.numbers.search(
+    service_slug="whatsapp",
+    country_code="NG",
+    min_score=80,
+    limit=5,
+)
+
+session = client.numbers.purchase(
+    service_slug="whatsapp",
+    country_code="NG",
+)
+
+def handle(push):
+    print(f"OTP: {push.otp} in {push.latency_ms}ms")
+
+client.subscribe(session.session_token, handle)
+```
+
+Note: `purchase()` takes `service_slug` + `country_code`, not a specific
+`number_id` -- the server picks the best available number by Health Score at
+purchase time, since a candidate returned by `search()` may already be gone
+by the time you'd reference it back.
+
+## Polling instead of real-time push
+
+`subscribe()` runs a background thread holding a persistent WebSocket
+connection, which isn't always practical (e.g. one-shot scripts, serverless
+functions). Use `sessions.wait_for_otp()` instead:
+
+```python
+result = client.sessions.wait_for_otp(session.session_token)
+if result.status == "DELIVERED":
+    print(result.otp_code)
+```
+
+## Errors
+
+All non-2xx responses raise `verixo.VerixoError` with `.status`, and usually
+`.code`/`.detail` from the API's error body:
+
+```python
+from verixo import VerixoError
+
+try:
+    client.numbers.purchase(service_slug="whatsapp", country_code="NG")
+except VerixoError as err:
+    if err.status == 402:
+        print("Insufficient wallet balance")
+```
+
+## Requirements
+
+Python 3.8+.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate   # or `source .venv/bin/activate` on macOS/Linux
+pip install -e .
+python examples/quickstart.py   # requires VC_API_KEY env var, see file header
+```

verixo-0.1.0/examples/quickstart.py

@@ -0,0 +1,36 @@
+"""
+Run against a local dev gateway:
+    VC_API_KEY=<your JWT or vc_test_/vc_live_ key> python examples/quickstart.py
+"""
+
+import os
+import time
+
+import verixo
+
+client = verixo.Client(
+    os.environ["VC_API_KEY"],
+    base_url=os.environ.get("VC_BASE_URL", "http://localhost:8080"),
+)
+
+result = client.numbers.search(service_slug="whatsapp", country_code="NG", min_score=0, limit=5)
+top_score = result.numbers[0].health_score if result.numbers else None
+print(f"Found {len(result.numbers)} numbers, top score: {top_score}")
+
+session = client.numbers.purchase(service_slug="whatsapp", country_code="NG", test_mode=True)
+print(f"Purchased {session.e164_number}, session {session.session_token}")
+
+received = {"done": False}
+
+
+def handle(push: verixo.OtpPush) -> None:
+    print(f"OTP: {push.otp} in {push.latency_ms}ms")
+    received["done"] = True
+
+
+unsubscribe = client.subscribe(session.session_token, handle)
+for _ in range(50):
+    if received["done"]:
+        break
+    time.sleep(0.2)
+unsubscribe()

verixo-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "verixo"
+version = "0.1.0"
+description = "Official Python SDK for the Verixo OTP-as-a-Service API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+keywords = ["otp", "sms-verification", "verixo", "phone-verification"]
+dependencies = [
+    "requests>=2.27",
+    "websocket-client>=1.6",
+]
+
+[project.urls]
+Homepage = "https://verifiedcore.com"
+Repository = "https://github.com/titicodes/verixo"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/verixo"]
+
+[tool.mypy]
+strict = true

verixo-0.1.0/src/verixo/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .client import HttpClient
+from .errors import VerixoError
+from .resources.analytics import Analytics
+from .resources.numbers import Numbers
+from .resources.sessions import Sessions
+from .subscribe import subscribe as _subscribe
+from .types import (
+    DeliveryRate,
+    DeliveryRates,
+    OtpPush,
+    PurchaseResult,
+    SearchNumbersResult,
+    SessionStatus,
+    VirtualNumber,
+)
+
+__all__ = [
+    "Client",
+    "VerixoError",
+    "VirtualNumber",
+    "SearchNumbersResult",
+    "PurchaseResult",
+    "SessionStatus",
+    "DeliveryRate",
+    "DeliveryRates",
+    "OtpPush",
+]
+
+
+class Client:
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: float = 30) -> None:
+        self._http = HttpClient(api_key, base_url, timeout=timeout)
+        self.numbers = Numbers(self._http)
+        self.sessions = Sessions(self._http)
+        self.analytics = Analytics(self._http)
+
+    def subscribe(self, session_token: str, on_otp: Callable[[OtpPush], None]) -> Callable[[], None]:
+        """
+        Get pushed the OTP for a session in real time, instead of polling
+        ``sessions.wait_for_otp()``. Returns an unsubscribe function.
+
+        Example::
+
+            session = client.numbers.purchase(service_slug="whatsapp", country_code="NG")
+
+            def handle(push):
+                print(f"OTP: {push.otp} in {push.latency_ms}ms")
+
+            client.subscribe(session.session_token, handle)
+        """
+        return _subscribe(self._http, session_token, on_otp)

verixo-0.1.0/src/verixo/client.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import VerixoError
+
+_DEFAULT_BASE_URL = "https://api.verixo.com"
+
+
+class HttpClient:
+    def __init__(self, api_key: str, base_url: Optional[str] = None, timeout: float = 30) -> None:
+        if not api_key:
+            raise ValueError("Verixo: an API key (or JWT) is required, e.g. Client('vc_test_...')")
+        self.api_key = api_key
+        self.base_url = (base_url or _DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    @property
+    def _authorization_header(self) -> str:
+        # The gateway classifies the credential by sniffing the raw Authorization header for a
+        # vc_test_/vc_live_ prefix -- a "Bearer " prefix on an API key would make it misclassify
+        # the request as a (malformed) JWT and reject it, so API keys go out unprefixed.
+        is_api_key = self.api_key.startswith("vc_test_") or self.api_key.startswith("vc_live_")
+        return self.api_key if is_api_key else f"Bearer {self.api_key}"
+
+    def request(self, method: str, path: str, *, json: Optional[Dict[str, Any]] = None) -> Any:
+        response = self._session.request(
+            method,
+            f"{self.base_url}{path}",
+            json=json,
+            headers={"Authorization": self._authorization_header},
+            timeout=self.timeout,
+        )
+        if not response.ok:
+            raise VerixoError.from_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def get(self, path: str) -> Any:
+        return self.request("GET", path)
+
+    def post(self, path: str, json: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("POST", path, json=json)
+
+    @property
+    def ws_origin(self) -> str:
+        """ws:// or wss:// origin derived from base_url, for the OTP push subscription."""
+        if self.base_url.startswith("https"):
+            return "wss" + self.base_url[len("https"):]
+        return "ws" + self.base_url[len("http"):]

verixo-0.1.0/src/verixo/errors.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+_STATUS_FALLBACKS = {
+    401: "Missing or invalid API key.",
+    402: "Insufficient wallet balance.",
+    403: "You don't have access to this resource.",
+    404: "Not found.",
+    408: "Request timed out.",
+    422: "The request did not meet a required condition (e.g. min_score).",
+    429: "Rate limit exceeded.",
+}
+
+
+class VerixoError(Exception):
+    """Raised for any non-2xx response from the Verixo API.
+
+    ``status`` is always present; ``code``/``detail`` are populated when the
+    gateway returns a JSON error body (most do) -- a small number of paths
+    (e.g. an invalid API key rejected before reaching a controller) return an
+    empty body, in which case only ``status`` and a generic message are
+    available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: Optional[str] = None,
+        detail: Optional[str] = None,
+        raw: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.detail = detail
+        self.raw = raw
+
+    @classmethod
+    def from_response(cls, response: Any) -> "VerixoError":
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+
+        obj = body if isinstance(body, dict) else {}
+        detail = obj.get("detail") or obj.get("error") or obj.get("message")
+        code = obj.get("grpcCode") or obj.get("code")
+        message = detail or _STATUS_FALLBACKS.get(
+            response.status_code, f"Request failed with status {response.status_code}"
+        )
+
+        return cls(message, status=response.status_code, code=code, detail=detail, raw=body)

verixo-0.1.0/src/verixo/resources/analytics.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ..client import HttpClient
+from ..types import DeliveryRates
+
+
+class Analytics:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def rates(self, service_slug: str = "whatsapp") -> DeliveryRates:
+        """Public delivery-rate stats by country for a service. No auth required by the API itself."""
+        data = self._http.get(f"/api/v1/analytics/rates?serviceSlug={service_slug}")
+        return DeliveryRates._from_json(data)

verixo-0.1.0/src/verixo/resources/numbers.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Optional
+from urllib.parse import urlencode
+
+from ..client import HttpClient
+from ..types import PurchaseResult, SearchNumbersResult, _from_json
+
+
+class Numbers:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def search(
+        self,
+        service_slug: str,
+        country_code: Optional[str] = None,
+        min_score: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> SearchNumbersResult:
+        """Browse available numbers ranked by Health Score (TM). No purchase is made."""
+        params = {"serviceSlug": service_slug}
+        if country_code:
+            params["countryCode"] = country_code
+        if min_score is not None:
+            params["minScore"] = str(min_score)
+        if limit is not None:
+            params["limit"] = str(limit)
+        data = self._http.get(f"/api/v1/numbers/search?{urlencode(params)}")
+        return SearchNumbersResult._from_json(data)
+
+    def purchase(
+        self,
+        service_slug: str,
+        country_code: str,
+        *,
+        privacy_mode: bool = False,
+        test_mode: bool = False,
+        channel: str = "SMS",
+    ) -> PurchaseResult:
+        """
+        Buy a number for a service + country. The server picks the best available
+        candidate by Health Score automatically -- there's no number_id parameter,
+        since by the time you'd pass one back the number may already be gone.
+        """
+        body = {
+            "serviceSlug": service_slug,
+            "countryCode": country_code,
+            "privacyMode": privacy_mode,
+            "testMode": test_mode,
+            "channel": channel,
+        }
+        data = self._http.post("/api/v1/numbers/purchase", json=body)
+        return _from_json(PurchaseResult, data)

verixo-0.1.0/src/verixo/resources/sessions.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import time
+from urllib.parse import quote
+
+from ..client import HttpClient
+from ..types import SessionStatus, _from_json
+
+
+class Sessions:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, session_token: str) -> SessionStatus:
+        """Poll a session's current delivery status."""
+        data = self._http.get(f"/api/v1/numbers/session/{quote(session_token)}")
+        return _from_json(SessionStatus, data)
+
+    def wait_for_otp(
+        self,
+        session_token: str,
+        timeout: float = 90,
+        interval: float = 2,
+    ) -> SessionStatus:
+        """
+        Poll until the session reaches a terminal state (DELIVERED, REFUNDED, EXPIRED,
+        FAILED) or the timeout elapses. Prefer ``Verixo.subscribe()`` for real-time
+        push -- this is a fallback for environments where a persistent WebSocket isn't
+        practical (e.g. serverless functions, simple scripts).
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            session = self.get(session_token)
+            if session.status != "PENDING":
+                return session
+            if time.monotonic() >= deadline:
+                return session
+            time.sleep(interval)

verixo-0.1.0/src/verixo/subscribe.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Dict, List
+
+import websocket
+
+from .client import HttpClient
+from .types import OtpPush, _from_json
+
+_NULL = "\x00"
+
+
+@dataclass
+class _StompFrame:
+    command: str
+    headers: Dict[str, str]
+    body: str
+
+
+def _build_frame(command: str, headers: Dict[str, str], body: str = "") -> str:
+    header_lines = "\n".join(f"{k}:{v}" for k, v in headers.items())
+    return f"{command}\n{header_lines}\n\n{body}{_NULL}"
+
+
+def _parse_frame(raw: str) -> _StompFrame:
+    head, _, body = raw.partition("\n\n")
+    lines = head.split("\n")
+    command = lines[0]
+    headers: Dict[str, str] = {}
+    for line in lines[1:]:
+        if ":" in line:
+            key, _, value = line.partition(":")
+            headers[key] = value
+    return _StompFrame(command=command, headers=headers, body=body.rstrip(_NULL))
+
+
+def subscribe(http: HttpClient, session_token: str, on_otp: Callable[[OtpPush], None]) -> Callable[[], None]:
+    """
+    Get pushed the OTP for a session in real time over the gateway's WebSocket
+    proxy (wss://.../ws -> delivery-service's STOMP broker, topic
+    /topic/otp/{session_token}), instead of polling ``sessions.wait_for_otp()``.
+
+    Runs the connection on a background thread and returns immediately with an
+    unsubscribe function. ``on_otp`` fires at most once per session (a session
+    only ever delivers one OTP).
+    """
+    subscribed_at = time.monotonic()
+    destination = f"/topic/otp/{session_token}"
+    buffer: List[str] = []
+
+    def handle_frame(raw: str) -> None:
+        frame = _parse_frame(raw)
+        if frame.command == "MESSAGE" and frame.headers.get("destination") == destination:
+            try:
+                payload = json.loads(frame.body)
+            except (ValueError, TypeError):
+                return
+            payload["latencyMs"] = int((time.monotonic() - subscribed_at) * 1000)
+            on_otp(_from_json(OtpPush, payload))
+
+    def on_open(ws: websocket.WebSocketApp) -> None:
+        ws.send(_build_frame("CONNECT", {"accept-version": "1.2", "heart-beat": "0,0"}))
+
+    def on_message(ws: websocket.WebSocketApp, message: str) -> None:
+        buffer.append(message)
+        joined = "".join(buffer)
+        if _NULL not in joined:
+            return
+        frames, _, remainder = joined.rpartition(_NULL)
+        buffer.clear()
+        if remainder:
+            buffer.append(remainder)
+        for raw in filter(None, frames.split(_NULL)):
+            if raw.strip().startswith("CONNECTED"):
+                ws.send(_build_frame("SUBSCRIBE", {"id": "sub-0", "destination": destination}))
+            else:
+                handle_frame(raw)
+
+    app = websocket.WebSocketApp(
+        f"{http.ws_origin}/ws",
+        on_open=on_open,
+        on_message=on_message,
+    )
+    thread = threading.Thread(target=app.run_forever, kwargs={"reconnect": 5}, daemon=True)
+    thread.start()
+
+    def unsubscribe() -> None:
+        app.close()
+
+    return unsubscribe

verixo-0.1.0/src/verixo/types.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, fields
+from typing import Any, Dict, List, Optional, Type, TypeVar
+
+T = TypeVar("T")
+
+_CAMEL_RE = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def _to_snake(name: str) -> str:
+    return _CAMEL_RE.sub("_", name).lower()
+
+
+def _from_json(cls: Type[T], data: Dict[str, Any]) -> T:
+    """Builds a dataclass from a camelCase JSON dict, mapping keys to snake_case fields."""
+    snake = {_to_snake(k): v for k, v in data.items()}
+    known = {f.name for f in fields(cls)}  # type: ignore[arg-type]
+    return cls(**{k: v for k, v in snake.items() if k in known})
+
+
+@dataclass
+class VirtualNumber:
+    number_id: str
+    number: str
+    e164_number: str
+    health_score: int
+    number_type: str
+    country_code: str
+    country_name: str
+    country_flag: str
+    price_usd: float
+    delivery_rate: float
+    avg_latency_ms: Optional[int]
+    available: bool
+    score_color: str
+    carrier_name: str
+
+
+@dataclass
+class SearchNumbersResult:
+    numbers: List[VirtualNumber]
+    total_available: int
+    country_code: str
+    service_slug: str
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "SearchNumbersResult":
+        result = _from_json(cls, data)
+        result.numbers = [_from_json(VirtualNumber, n) for n in data.get("numbers", [])]
+        return result
+
+
+@dataclass
+class PurchaseResult:
+    session_token: str
+    purchase_id: str
+    web_socket_topic: str
+    e164_number: str
+    health_score_at_purchase: int
+    score_color: str
+    carrier_type: str
+    aggregator_type: str
+    price_usd: float
+    sla_remaining_seconds: int
+    sla_expires_at: str
+    privacy_mode: bool
+    confidence_label: str
+    channel: str
+
+
+@dataclass
+class SessionStatus:
+    session_token: str
+    status: str  # "PENDING" | "DELIVERED" | "REFUNDED" | "EXPIRED" | "FAILED"
+    otp_code: str
+    sla_remaining_seconds: int
+    failure_reason: str
+    aggregator_type: str
+    health_score: int
+    privacy_mode: bool
+    channel: str
+
+
+@dataclass
+class DeliveryRate:
+    country_code: str
+    country_name: str
+    country_flag: str
+    rate: float
+    latency: str
+    total_deliveries: int
+    updated_at: str
+
+
+@dataclass
+class DeliveryRates:
+    rates: List[DeliveryRate]
+    updated_at: str
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "DeliveryRates":
+        return cls(
+            rates=[_from_json(DeliveryRate, r) for r in data.get("rates", [])],
+            updated_at=data.get("updatedAt", ""),
+        )
+
+
+@dataclass
+class OtpPush:
+    session_token: str
+    otp: str
+    e164_number: str
+    service_slug: str
+    privacy_mode: bool
+    delivered_at: str
+    latency_ms: int
+    """Milliseconds between calling subscribe() and this push arriving -- not from the server."""