lessotp-sdk 0.1.0__tar.gz

lessotp_sdk-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Dependencies
+node_modules/
+vendor/
+.venv/
+venv/
+.env/
+
+# Build outputs
+dist/
+build/
+coverage/
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# JavaScript / package managers
+.bun/
+.npm/
+.pnpm-store/
+.yarn/
+*.tsbuildinfo
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Local env
+.env
+.env.*
+!.env.example
+!.env.*.example

lessotp_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lessotp-sdk"
+version = "0.1.0"
+description = "LessOTP Inbound WhatsApp Authentication client SDK for Python."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "LessOTP" }]
+keywords = ["lessotp", "whatsapp", "authentication", "verification", "passwordless"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://lessotp.com"
+Repository = "https://github.com/lessotp/sdk"
+Issues = "https://github.com/lessotp/sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lessotp_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

lessotp_sdk-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import threading
+from urllib import error as urlerror
+
+import pytest
+
+from lessotp_sdk import (
+    DEFAULT_ENVIRONMENT,
+    LessOTPClient,
+    LessOTPError,
+    parse_verified_webhook,
+    verify_webhook_signature,
+)
+
+
+class _Handler(BaseHTTPRequestHandler):
+    status = 200
+    response = {
+        "status": "success",
+        "data": {
+            "request_id": "req_abc",
+            "unique_code": "A7X92",
+            "wa_link": "https://wa.me/628999999999?text=%2FLOGIN%20A7X92",
+            "expires_in": 180,
+            "mode": "strict",
+        },
+    }
+    requests: list = []
+
+    def do_POST(self) -> None:  # noqa: N802
+        length = int(self.headers.get("content-length", "0"))
+        body = self.rfile.read(length).decode("utf-8")
+        self.__class__.requests.append(
+            {
+                "path": self.path,
+                "authorization": self.headers.get("authorization", ""),
+                "body": body,
+            }
+        )
+        raw = json.dumps(self.__class__.response).encode("utf-8")
+        self.send_response(self.__class__.status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+
+@pytest.fixture
+def server():
+    _Handler.status = 200
+    _Handler.response = {
+        "status": "success",
+        "data": {
+            "request_id": "req_abc",
+            "unique_code": "A7X92",
+            "wa_link": "https://wa.me/628999999999?text=%2FLOGIN%20A7X92",
+            "expires_in": 180,
+            "mode": "strict",
+        },
+    }
+    _Handler.requests = []
+    srv = HTTPServer(("127.0.0.1", 0), _Handler)
+    thread = threading.Thread(target=srv.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield srv
+    finally:
+        srv.shutdown()
+        thread.join(timeout=2)
+
+
+def _url(server: HTTPServer) -> str:
+    return "http://127.0.0.1:%d" % server.server_port
+
+
+def test_default_environment_is_production(server: HTTPServer) -> None:
+    client = LessOTPClient("key_test", base_url=_url(server))
+    assert client._environment == DEFAULT_ENVIRONMENT == "production"
+
+    client.auth_request("6281234567890")
+    assert _Handler.requests[0]["path"] == "/api/v1/auth/request"
+
+
+def test_constructor_environment_routes_to_staging(server: HTTPServer) -> None:
+    client = LessOTPClient("key_test", environment="staging", base_url=_url(server))
+    _Handler.response["data"]["request_id"] = "req_stage"
+
+    result = client.auth_request("6281234567890")
+    assert result.request_id == "req_stage"
+    assert _Handler.requests[0]["path"] == "/api/v1/staging/auth/request"
+
+
+def test_per_call_environment_override_beats_constructor(server: HTTPServer) -> None:
+    client = LessOTPClient("key_test", base_url=_url(server))
+    _Handler.response["data"]["request_id"] = "req_stage"
+
+    client.auth_request("6281234567890", environment="staging")
+    assert _Handler.requests[0]["path"] == "/api/v1/staging/auth/request"
+
+
+def test_auth_request_strict_posts_to_production_endpoint(server: HTTPServer) -> None:
+    client = LessOTPClient("key_test", base_url=_url(server))
+    result = client.auth_request("6281234567890")
+
+    assert result.request_id == "req_abc"
+    assert result.mode == "strict"
+    assert _Handler.requests[0]["path"] == "/api/v1/auth/request"
+    assert _Handler.requests[0]["authorization"] == "Bearer key_test"
+    assert json.loads(_Handler.requests[0]["body"]) == {"phone_number": "6281234567890"}
+
+
+def test_auth_request_frictionless_sends_empty_object(server: HTTPServer) -> None:
+    _Handler.response["data"]["mode"] = "frictionless"
+    client = LessOTPClient("key_test", base_url=_url(server))
+    result = client.auth_request()
+    assert result.mode == "frictionless"
+    assert json.loads(_Handler.requests[0]["body"]) == {}
+
+
+def test_non_2xx_raises_lessotp_error(server: HTTPServer) -> None:
+    _Handler.status = 401
+    _Handler.response = {"error": "invalid_api_key"}
+    client = LessOTPClient("bad", base_url=_url(server))
+    with pytest.raises(LessOTPError, match="401"):
+        client.auth_request()
+
+
+def test_unknown_environment_raises(server: HTTPServer) -> None:
+    with pytest.raises(LessOTPError, match="environment must be"):
+        LessOTPClient("k", environment="qa", base_url=_url(server))
+
+
+def test_verify_webhook_signature_accepts_hex_and_prefix() -> None:
+    body = json.dumps({"event": "verification.success", "request_id": "r1", "phone_number": "628"})
+    secret = "whsec_test"
+    sig = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
+
+    assert verify_webhook_signature(body, sig, secret) is True
+    assert verify_webhook_signature(body, "sha256=" + sig, secret) is True
+
+
+def test_verify_webhook_signature_rejects_bad_inputs() -> None:
+    assert verify_webhook_signature("{}", None, "secret") is False
+    assert verify_webhook_signature("{}", "abc", "secret") is False
+    assert verify_webhook_signature("{}", "a" * 64, "secret") is False
+    assert verify_webhook_signature("{}", "a" * 64, "") is False
+
+
+def test_parse_verified_webhook_returns_none_on_bad_signature() -> None:
+    body = json.dumps({"event": "verification.success", "request_id": "r1", "phone_number": "628"})
+    assert parse_verified_webhook(body, None, "secret") is None
+
+
+def test_parse_verified_webhook_parses_valid_payload() -> None:
+    payload = {
+        "event": "verification.success",
+        "request_id": "r1",
+        "phone_number": "6281234567890",
+        "timestamp": "2026-06-20T10:00:00Z",
+    }
+    body = json.dumps(payload)
+    secret = "secret"
+    sig = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
+
+    event = parse_verified_webhook(body, sig, secret)
+    assert event is not None
+    assert event.request_id == "r1"
+    assert event.phone_number == "6281234567890"
+    assert event.timestamp == "2026-06-20T10:00:00Z"
+
+
+def test_parse_verified_webhook_rejects_wrong_event() -> None:
+    payload = {"event": "verification.failed", "request_id": "r1", "phone_number": "628"}
+    body = json.dumps(payload)
+    secret = "secret"
+    sig = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
+
+    with pytest.raises(LessOTPError, match="unexpected webhook event"):
+        parse_verified_webhook(body, sig, secret)