lessotp-sdk 0.1.0__py3-none-any.whl

lessotp_sdk/__init__.py

@@ -0,0 +1,216 @@
+"""LessOTP Inbound WhatsApp Authentication API — client SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Optional, Union
+from urllib import error as urlerror
+from urllib import request as urlrequest
+
+DEFAULT_BASE_URL = "https://api.lessotp.com"
+DEFAULT_TIMEOUT_SECONDS = 10
+DEFAULT_ENVIRONMENT = "production"
+VALID_ENVIRONMENTS = ("production", "staging")
+RawBody = Union[str, bytes]
+
+
+class LessOTPError(RuntimeError):
+    """Surface error type for SDK consumers."""
+
+
+@dataclass(frozen=True)
+class AuthRequestResult:
+    """Normalized response from ``POST /api/v1/auth/request``."""
+
+    request_id: str
+    unique_code: str
+    wa_link: str
+    expires_in: int
+    mode: str
+
+    @classmethod
+    def from_response(cls, payload: Dict[str, Any]) -> "AuthRequestResult":
+        data = payload.get("data")
+        if not isinstance(data, dict):
+            raise LessOTPError("LessOTP response missing 'data' object")
+        required = ["request_id", "unique_code", "wa_link", "expires_in", "mode"]
+        for key in required:
+            if key not in data:
+                raise LessOTPError("LessOTP response missing '%s'" % key)
+        mode = str(data["mode"])
+        if mode not in {"strict", "frictionless"}:
+            raise LessOTPError(
+                "LessOTP response mode must be 'strict' or 'frictionless', got '%s'" % mode
+            )
+        return cls(
+            request_id=str(data["request_id"]),
+            unique_code=str(data["unique_code"]),
+            wa_link=str(data["wa_link"]),
+            expires_in=int(data["expires_in"]),
+            mode=mode,
+        )
+
+
+@dataclass(frozen=True)
+class VerificationSuccess:
+    """Canonical representation of a ``verification.success`` webhook payload."""
+
+    event: str
+    request_id: str
+    phone_number: str
+    timestamp: Optional[str] = None
+
+    @classmethod
+    def from_payload(cls, payload: Dict[str, Any]) -> "VerificationSuccess":
+        event = str(payload.get("event", ""))
+        if event != "verification.success":
+            raise LessOTPError("unexpected webhook event '%s'" % event)
+        request_id = payload.get("request_id")
+        phone_number = payload.get("phone_number")
+        if not isinstance(request_id, str) or not isinstance(phone_number, str):
+            raise LessOTPError("webhook payload missing request_id or phone_number")
+        timestamp = payload.get("timestamp")
+        return cls(
+            event=event,
+            request_id=request_id,
+            phone_number=phone_number,
+            timestamp=timestamp if isinstance(timestamp, str) else None,
+        )
+
+
+class LessOTPClient:
+    """Stateless HTTP client for the LessOTP API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        environment: str = DEFAULT_ENVIRONMENT,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        if not api_key:
+            raise LessOTPError("api_key is required")
+        self._api_key = api_key
+        self._environment = _resolve_environment(environment)
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+
+    def auth_request(
+        self,
+        phone_number: Optional[str] = None,
+        environment: Optional[str] = None,
+    ) -> AuthRequestResult:
+        """Create a verification request.
+
+        Endpoint is selected from the client environment. Pass ``environment``
+        to override for this call.
+        """
+
+        env = _resolve_environment(environment if environment is not None else self._environment)
+        return self._auth_request(_endpoint_for(env), phone_number)
+
+    def _auth_request(self, path: str, phone_number: Optional[str]) -> AuthRequestResult:
+        body = {} if phone_number is None else {"phone_number": phone_number}
+        raw_body = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        req = urlrequest.Request(
+            self._base_url + path,
+            data=raw_body,
+            method="POST",
+            headers={
+                "Authorization": "Bearer %s" % self._api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "lessotp-sdk-python/0.1.0",
+            },
+        )
+        try:
+            with urlrequest.urlopen(req, timeout=self._timeout_seconds) as response:
+                status = getattr(response, "status", response.getcode())
+                raw = response.read()
+        except urlerror.HTTPError as exc:
+            raw = exc.read().decode("utf-8", errors="replace")
+            raise LessOTPError("LessOTP auth_request failed: %s: %s" % (exc.code, raw)) from exc
+        except urlerror.URLError as exc:
+            raise LessOTPError("LessOTP auth_request transport error: %s" % exc.reason) from exc
+
+        if status < 200 or status >= 300:
+            raise LessOTPError(
+                "LessOTP auth_request failed: %s: %s"
+                % (status, raw.decode("utf-8", errors="replace"))
+            )
+
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except json.JSONDecodeError as exc:
+            raise LessOTPError("LessOTP response was not valid JSON") from exc
+        if not isinstance(payload, dict) or payload.get("status") != "success":
+            raise LessOTPError("LessOTP response missing 'status: success'")
+        return AuthRequestResult.from_response(payload)
+
+
+def _resolve_environment(value: Optional[str]) -> str:
+    if value is None or value == "":
+        return "production"
+    if value not in VALID_ENVIRONMENTS:
+        raise LessOTPError(
+            "LessOTP environment must be 'production' or 'staging', got '%s'" % value
+        )
+    return value
+
+
+def _endpoint_for(environment: str) -> str:
+    if environment == "staging":
+        return "/api/v1/staging/auth/request"
+    return "/api/v1/auth/request"
+
+
+def verify_webhook_signature(
+    raw_body: RawBody,
+    signature_header: Optional[str],
+    secret: str,
+) -> bool:
+    """Return true when ``signature_header`` is a valid HMAC-SHA256."""
+
+    if not signature_header or not secret:
+        return False
+    stripped = signature_header.strip()
+    if stripped.lower().startswith("sha256="):
+        stripped = stripped[7:]
+    if len(stripped) == 0 or len(stripped) % 2 != 0:
+        return False
+    try:
+        provided = bytes.fromhex(stripped)
+    except ValueError:
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).digest()
+    return hmac.compare_digest(expected, provided)
+
+
+def parse_verified_webhook(
+    raw_body: RawBody,
+    signature_header: Optional[str],
+    secret: str,
+) -> Optional[VerificationSuccess]:
+    """Verify and parse a LessOTP ``verification.success`` webhook payload."""
+
+    if not verify_webhook_signature(raw_body, signature_header, secret):
+        return None
+    text = raw_body.decode("utf-8") if isinstance(raw_body, bytes) else raw_body
+    payload = json.loads(text)
+    if not isinstance(payload, dict):
+        raise LessOTPError("webhook payload is not an object")
+    return VerificationSuccess.from_payload(payload)
+
+
+__all__ = [
+    "AuthRequestResult",
+    "LessOTPClient",
+    "LessOTPError",
+    "VerificationSuccess",
+    "parse_verified_webhook",
+    "verify_webhook_signature",
+]

lessotp_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: lessotp-sdk
+Version: 0.1.0
+Summary: LessOTP Inbound WhatsApp Authentication client SDK for Python.
+Project-URL: Homepage, https://lessotp.com
+Project-URL: Repository, https://github.com/lessotp/sdk
+Project-URL: Issues, https://github.com/lessotp/sdk/issues
+Author: LessOTP
+License-Expression: MIT
+Keywords: authentication,lessotp,passwordless,verification,whatsapp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# LessOTP Python SDK
+
+Client for the **LessOTP Inbound WhatsApp Authentication API** (Python 3.8+).
+
+## Install
+
+```bash
+pip install lessotp-sdk
+```
+
+## Usage
+
+```python
+import os
+from lessotp_sdk import LessOTPClient, parse_verified_webhook
+
+# production (default)
+client = LessOTPClient(api_key=os.environ["LESSOTP_API_KEY"])
+
+# staging
+staging = LessOTPClient(
+    api_key=os.environ["LESSOTP_STAGING_API_KEY"],
+    environment="staging",
+)
+
+# strict
+strict = client.auth_request("6281234567890")
+
+# frictionless
+frictionless = client.auth_request()
+
+# per-call override
+one_off = client.auth_request("6281234567890", environment="staging")
+
+# webhook verification
+event = parse_verified_webhook(
+    request.get_data(as_text=True),
+    request.headers.get("X-Signature"),
+    os.environ["LESSOTP_WEBHOOK_SECRET"],
+)
+if event is None:
+    return "bad signature", 403
+print(event.request_id, event.phone_number)
+```
+
+## API
+
+### `LessOTPClient(api_key, environment='production', base_url='https://api.lessotp.com', timeout_seconds=10)`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | required | App API key. |
+| `environment` | `"production"` | `"production"` or `"staging"`. |
+| `base_url` | `https://api.lessotp.com` | API host. |
+| `timeout_seconds` | `10` | HTTP timeout. |
+
+### `client.auth_request(phone_number=None, environment=None) -> AuthRequestResult`
+
+Calls the endpoint selected by `environment`. The per-call `environment` overrides the client environment.
+
+### `verify_webhook_signature(raw_body, signature_header, secret) -> bool`
+
+Constant-time HMAC-SHA256 verification. Accepts raw hex and `sha256=` prefixed values.
+
+### `parse_verified_webhook(raw_body, signature_header, secret) -> VerificationSuccess | None`
+
+Returns the parsed payload if the signature is valid; `None` otherwise.
+
+## Errors
+
+Raises `LessOTPError` on transport, auth, or payload problems.
+
+## Tests
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+```

lessotp_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+lessotp_sdk/__init__.py,sha256=-N8drS8hg7W2K562G8358B2OeHnsIC6gZ8ejrD9jY5A,7507
+lessotp_sdk-0.1.0.dist-info/METADATA,sha256=1meM89JBRyxOejJFDystf-2iWIQYwbUir8byT789dLw,2982
+lessotp_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+lessotp_sdk-0.1.0.dist-info/RECORD,,

lessotp_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any